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In our five years of publishing for OS/2 application developers, we have learned what 
programmers need: real-life, function-filled, practical programming examples. Both new 
and intermediate developers seem to learn best from good source code samples. Often, 
they will cut and paste, building a new application on a working base, learning as they 
g°- 

Real-World Programming for OS/2 2.1 understands and meets that need. This book 
is filled with practical, meaty tips and techniques about OS/2 programming. The authors 
deliver their considerable experience in the form of useful sample programs and narra¬ 
tive. They have tested their code on four popular OS/2 compilers, and they have pro¬ 
vided it on a diskette for the convenience of their readers. 

This book sets a new standard in practical programming. The authors are to be con¬ 
gratulated! 


Dick Conklin 
Editor 

OS/2 Developer Magazine 
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The Nature of This Book 


More than likely you bought this book because you have a programming problem to solve. 
That’s the reason we wrote it. We know from experience that the way to start program¬ 
ming on a new platform and the way to solve many programming tasks is not to stand 
back theorizing for a couple of weeks about how it should be done. Instead, 


you get a good example to work from, then tear into it with your own 
additions and changes. Now, more than likely, your first efforts 
W serve only as a stepping stone for later development, but 

: X ■ you need that initial experience to build on. 
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Trouble is, many times the software development kits do not have the room to 
provide examples for you to work with, and the last thing the world needs is another 
programming book showing you how to write another “Hello, World” program, only 
for OS/2. This book covers areas of programming that are largely ignored or poorly ex¬ 
emplified in software development kits and documentation. It is aimed at intermediate 
level programmers. This does not mean you must be an intermediate level programmer 
for OS/2, only that you should have the habit of analysis and be familiar with coding 
concepts that come with programming experience. 

Again, the emphasis is on developing code and techniques directly applicable to your 
programming efforts. Each sample application in this book is designed as a framework 
on which you can found your efforts. General areas of knowledge covered are message- 
based architecture, working with OS/2 windows, working with fonts, working with print¬ 
ers, creating DLLs, interprocess coordination, menus, and drawing. Although you can 
work from the front to the back, it is not necessary to follow only that path. We suggest 
that you first work through Chapters 2, “OS/2 Application Window Fundamentals, 3, 
“Window Management,” and 4, “2.1 Common Dialogs,” consecutively. After that, you 
should be able to dive into the chapters that apply to your particular need. 

The sample applications in this book are longer than usual, but we felt this was nec¬ 
essary to provide you with a useful framework. As a result, there is not a line-by-line dis¬ 
cussion of each sample; otherwise, the book would have been huge! We suggest you first 
read the discussion about the concepts and important API entries at the beginning of 
each chapter. After that, load the working executable from the companion disk and spend 
some time working with it. This will help familiarize you with the general issues involved. 
Then, you can begin working through the code to see how the general concepts and 
behavior of the application have been realized in the code. 

The applications in this book use the graphical user interface facilities provided by 
the Presentation Manager API of OS/2. This continues to be an area in which many 
programmers need some assistance. Don’t forget that OS/2 still allows character-based 
applications to run perfectly well in a window or full-screen session. These types of 
applications just aren’t the focus of this book. 

This is a book designed to help you solve some of the more difficult issues involved 
in creating a nontrivial program for OS/2. We have tried to address the issues that 
programmers frequently face—things like how to open a file by using the common file 
dialogs and how to use multithreading. 

That’s what the book is, but we should also say a word about what the book is not. 
This is not a programming manual about how to program in C. There simply isn t room. 
This book also is not simply a recapitulation of the OS/2 Technical Library. We have 
tried to distill the essential elements; we have tried to bring together things that are some¬ 
times located all over the documentation in several different manuals; and we hope this 
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helps; but really this book is a collection of applications that shows how to get something 
done—something usually fairly complicated. We tried to go far beyond the examples you 
will see both in the documentation for OS/2 and for the compiler that you will be using. 

You are welcome to build applications on the code that we supply with the book. 
We, however, do insist that you do not redistribute the software or the code from this 
book without substantial modification and addition on your part. 

If you have not built an application for OS/2 yet with your compiler, we certainly 
recommend working through one of the smaller examples supplied with the compiler 
before tackling one of the applications in this book. This will ensure that your environ¬ 
ment is set up correctly and will save you a considerable amount of frustration. 

Each application on the disk that accompanies the book has a number of files associ¬ 
ated with it. There is a compiled executable, along with a command file, a make file, and 
the C, DEF, RC, ICO, DLG, and all the other files necessary to build the application. 
To begin understanding the applications, we suggest you first use the compiled versions 
that are shipped on the disk. 

Compilers Used 

We wrote the sample applications for this book to be compatible with the four major C 
compilers in the OS/2 environment. These are the Watcom, Borland, Zortech, and IBM 
C Set/2 compilers. Each has its own characteristics, which may make one more desirable 
than another. 

Building the Applications 

The fact that a suite of applications could actually be made compatible across all these 
compilers says volumes about the stability of the platform and the tools developed for it. 
Each application has been provided with a make file that can be used to build the appli¬ 
cation for each of the compiler products. This process is described in greater detail in this 
chapter in the section Building a Sample Application.” You can, of course, use the inte¬ 
grated development environments provided with the compilers. Merely follow their in¬ 
structions about where to place particular modules, switches, and so forth. 

Installing Your Compiler 

Each of the compilers installs in a different way. You must follow the instructions for the 
compiler you plan to use. Further, we suggest that you practice with some of the smaller 
examples provided with your compiler. This will ensure that your development environ¬ 
ment is set up correctly before you take on some of the larger projects that accompany 
this book. We strongly suggest you ensure that the PATH, INCLUDE, and LIBPATH envi¬ 
ronment variables are set correctly. 
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Installing the Software 

We have provided an installation program with the software. This installation program 
will copy the software from the companion distribution disk to your hard drive. It will 
also ensure that the proper directory structure to contain the software is set up on your 
hard drive. 

To use the installation program, start an OS/2 session, either full screen or in a win¬ 
dow. Change to the drive containing the distribution disk. Then, type this command: 

INSTALL 

First, the installation program will present you with the screen shown in Figure 1.1. 


Figure 1.1. 

Opening screen shot file. 



Welcome to the Rea! World Programming (or OS/2 source code installation 
program.: The installation process will copy the source code lor the selected 
chapters onto'your'computer. 

' • ■ 

Enter the drive and directory to install the chapters into: 

JcTwP0S2_ ___ 


Chapters to install: 


jVf Create Folder 


Dish Space Required;. 


Cancel 
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You may choose which chapters to install. You may also select a check box to cause 
the installation program to place all the programs automatically in a folder on the desk¬ 
top. You may also change the root directory under which the software will be installed. If 
you do not make a change to the default directory name, the software will be installed in 
a directory structure by chapter under a directory named \RWPOS2. 

Once the installation has begun, you will be presented with the dialog box shown in 
Figure 1.2. 

This dialog box will change to show the progression of the installation. 

Building a Sample Application 

After your compiler is installed on your system and the sample software is installed, you 
are almost ready to build the samples. Notice that executable versions of the samples are 
shipped for each chapter. You do not have to run the make utility to use the programs. 
We included the make files, however, because more than likely you will want to make 
additions and changes to the samples. 





Chapter 1 Programming for OS/2 


Figure 1.2. 
Dialog box file. 
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cfco2 DfiveC 

Percent Complete 


First, before building any of the applications, you need to indicate which of the com¬ 
pilers you will be using to create the application. This is done by setting an environment 
variable for the compiler. This environment variable is used in the command file to de¬ 
termine which of the compilers to use to build the application for the GO command file. 

To set up the environment variable use this command: 

SET C0MPILER= 

You may choose from these: 

BORLAND 

WATCOM 

IBMC 

ZORTECH 

CL386 

For example, if you are using the Watcom compiler, enter this command: 

SET COMPILER=WATCOM 

To make it even easier, we suggest making this line a part of your CONFIG.SYS file. 

There is a file common to all the applications. This is the About box. Before you can 
build any of the applications, this needs to be created with the compiler that you will be 
using. After you have set the environment variable, therefore, change to the \COMMON 
directory and enter the GO command. You are now ready to begin building the samples. 

Each sample is built by using the following: 

® The modules that make up the application code. These include C code 
modules, resources, and include files. 

® A file that is a list of dependencies for each sample. This file will have the 
extension .DEP. 

# A make file for each of the four compilers. 

# An OS/2 command file that starts the make process. 
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The SKELETON application, for example, will have these files in its installed 
directory: 

SKELETON.DEP 

SKELETON.H 

SKELETON.DEF 

GO.CMD 

SKELETON.C 

SKELETON.RC 

SKELETON.OBJ 

SKELETON.RES 

SKELETON.MAP 

SKELETON.ICO 

SKELETON.EXE 

To build this sample, change to the directory that contains these files and enter the 
following command: 


This will cause the command file to start the build for the SKELETON application. 
The actual lines in the command file are as follows: 

@ECHO 
@ECHO 
@ECHO 
@ECHO 
@ECHO 
@ECHO 

@if 11 %COMPILER%" ==" 11 goto nocompiler 

@if %C0MPILER%==CL386 set MAKECMD=nmake 

@if %C0MPILER%==cl386 set MAKECMD=nmake 

@if %COMPILER%==BORLAND set MAKECMD=make 

@if %COMPILER%==borland set MAKECMD=make 

@if %C0MPILER%==IBMC set MAKECMD=nmake 

@if %COMPILER%==ibmc set MAKECMD=nmake 

@if %COMPILER%==WATCOM set MAKECMD=wmake 

@if %COMPILER%==watcom set MAKECMD=wmake 

@if %COMPILER%==ZORTECH set MAKECMD=make 

@if %COMPILER%==zortech set MAKECMD=make 

%MAKECMD% -f ..\%COMPILER%.mak MAKEFILE=skeleton.dep 

@goto done 

: nocompiler 

@ECHO 

@ECH0 »»» COMPILER environment variable must be set to compiler name 
@ECHO 
: done 


Skeleton Application 
Chapter 2 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 
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The make file follows the usual structure. There is a make file for each of the compil¬ 
ers supported. Each of these is in the root directory where you installed the distributed 
files. Let’s say you are using the Borland compiler. The make file for this compiler has 
these lines: 

# Borland C++ for OS/2 

# Compiler Definition File 

# Real-World Programming for OS/2 2.1 

# Copyright (c) 1993 Blain, Delimon, and English 

# Inference rules 

BORLANDEXEOPTS = -m -aa -Toe -L$(LIB) 

BORLANDDLLOPTS = -m -Tod -L$(LIB) 

ABOUT = ..\common\about.obj 

.c.obj : 

@echo »»» 

@echo ««« Compiling $*.c using Borland options »»» 

@echo »»» 

bcc -c -K -w -D_BORLAND_$ (BORLANDOPTS) $*.c > $*.err 

type $*.err 

.asm.obj : 

@echo »»» 

@echo ««« Assembling $*.asm using MASM386 options »»» 

@echo »»» 

tasm -ml -mx -d_TASM_-oi -w2 $* . asm,$* .obj ; 

.rc.res : 

@echo »»» 

@echo ««« Running resource compiler on $*.rc »»» 

@echo »»» 
rc -r $*.rc 

.def.lib : 

@echo »»» 

@echo ««« Creating import library from $*.def »»» 

@echo »»» 

implib $*.lib $*.def 

.obj.exe : 

@echo »»» 

@echo ««« Building $*.exe using Borland options »»» 

@echo »»» 
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tlink $(BORLANDEXEOPTS) C02 $(0BJS) $(ABOUT),$*.exe,$*.map,$(LIBS) 
c2 os2386,$*.def 

rc $*.res $*.exe 

.obj.dll : 

Oecho »»» 

@echo ««« Building $*.dll using Borland options »»» 

@echo »»» 

tlink $(BORLANDDLLOPTS) $(OBJS) 

$(BORLANDINITOBJ),$*.dll 3 $*.map,$(LIBS) OS2386,$*.def 

rc $*.res $*.dll 

!include $(MAKEFILE) 

# MEMINST.OBJ must be built this way to force the _INSTANCEDATA segment 

# to be placed in a separate segment from the _DATA segment 

# The -oi option of tasm creates the correct kind of object record 

# for the linker 
meminst.obj : meminst.c 

bcc -C -K -w -S -D_BORLAND_-zR_INSTANCEDATA -zTFAR_DATA 

$(BORLANDOPTS) $*.c > $*.err 

tasm -ml -mx -d_TASM_-oi -w2 $*.asm,$*.obj; 

del $*.asm 


This file, in turn, depends on a file that lists the dependencies for the particular sam¬ 
ple being made. There is a dependency file for each sample. In Chapter 2, “OS/2 Appli¬ 
cation Window Fundamentals,” in the SKELETON application, the dependency file is 
named SKELETON.DEP. It contains these lines: 

# Skeleton Dependencies Make File 

# Chapter 2 

# Real-World Programming for OS/2 2.1 

# Copyright (c) 1993 Blain, Delimon, and English 

# Dependencies and Build Items 

OBJS = skeleton.obj 
all: skeleton.exe 

skeleton.obj: skeleton.c skeleton.h 
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skeleton.res: skeleton.rc skeleton.ico 
skeleton.exe: $(OBJS) skeleton.res skeleton.def 

Heading Out on Your Own 

After you have built a few of the applications just as they are installed, you can begin to 
modify them to suit your own purposes. We suggest making small changes at first. This 
will keep you from getting too far off the track. 

Write if you get work. 






OS/2 Application 
Window 
Fundamentals 


Windows 

OS/2 2.1 Presentation Manager applications are organized around the concept of 
windows. Windows in PM applications are not simply rectangular areas on the video 
screen. They are sets of structures, queues, data, and characteristics that define how the 
application, the user, and the operating system will interact. The windows 
of an application are the means by which the application and the user 
communicate. 

The operating system also communicates with the appli¬ 
cation by sending messages to the application’s windows. Your 
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application code associated with the window is responsible for responding to or process¬ 
ing these messages. These messages can contain input from the keyboard, or even notifi¬ 
cation from the operating system that a window should destroy itself. This interaction, 
the posting and processing of messages, can be complex. Fortunately, when your appli¬ 
cation creates a window, much of the behavior of that window is defined automatically. 
You are then able to add code that concentrates on the particular messages and behavior 
that are the focus of your application. 

The sample application, SKELETON, detailed in subsequent text, illustrates the 
creation and destruction of a simple window. However, before you can begin a line-by¬ 
line analysis of that code, you must understand some basic concepts. First to examine are 
the relationships that may exist among the various windows that may be on the Presen¬ 
tation Manager desktop. There are two fundamental relationships with which you must 
be concerned. One is a parent-child relationship; the other is ownership. These are inde¬ 
pendent relationships and must be understood separately. 

Parent-Child Relationship 

The windows open during a Presentation Manager (PM) session are organized in a hier¬ 
archy. At the top of the hierarchy is the desktop window. OS/2 creates the desktop win¬ 
dow when PM is started. Windows created by applications running under PM make up 
the next level. These windows are called main windows or top-level windows. These main 
windows may, in turn, have other windows that belong to them. You may think of these 
in terms of a parent-child relationship. 

For example, if you start OS/2 on your computer and then open an application, the 
computer’s video screen will display something like Figure 2.1. One main window is open 
that also has a child window open. The desktop window is the parent of Draw for OS/2’s 
main window, which is in turn the parent of the Page window. 

All windows, except the desktop window, have a parent window. (There is another 
type of window without a parent. It is the desktop-object window, which we will return 
to much later.) An application designates the parent to a window when it is created. A 
window can have only a single parent window, but it may have any number of child 
windows. The operating system uses this relationship between the parent and child win¬ 
dows to determine several important things described later. 

The rules governing parent-child window relationships apply to all windows at all 
times. These cannot be modified. Location and arrangement of the windows also is 
governed by this parent-child relationship. You can see that all main windows are sib¬ 
lings because they all share the common parent of the desktop window. Sibling windows 
may overlap. Users may arrange these sibling windows in whatever order desired. The 
parent window, however, will always be at the bottom of the stack. The desktop win¬ 
dow, therefore, will always be behind all the main windows, and all the child windows of 
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an application’s main window will be in front of that main window. Figure 2.2 shows 
the parental hierarchy of the desktop, application windows, and a dialog window or 
dialog box. 


Figure 2.1. 

A typical desktop. 
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The child window is drawn relative to its parent. A main window is drawn relative to 
the lower-left corner of the desktop window. The child window of an application is drawn 
relative to the lower-left corner of its main window. A child window is never drawn out¬ 
side the region of its parent window. Any part of the child window that extends outside 
the borders of its parent window is not drawn. 

Strangely, an application may change the parent of a child window at any time using 
the WinSetParent function. When the parent window is changed, the child window is 
immediately redrawn inside the region of its new parent. It also takes on the styles that 
belong to the new parent. 

The parent-child relationship also governs what happens when windows are hidden, 
minimized, or destroyed. When an application is terminated, every child window is de¬ 
stroyed before its parent. The child windows are destroyed at the lowest level of 
descendency up to the main parent window. When a parent window is minimized, the 
parent window is actually hidden. Because the parent is now hidden, none of its children 
are visible. The actual activity of the operating system is slightly different than IBM’s 
official documentation implies. The operating system does not step through minimizing 
all the child windows. The child window takes on some of the attributes of its parent; if 
the parent window’s visibility state changes to not visible, none of its children are visible. 

When it determines a window must be redrawn, the operating system makes the 
determination that because none of the parents are visible, none of the descendants are 
visible. The WS_VISIBLE flag of the children’s window style, however, is unchanged. 
Likewise, if a parent window is disabled, none of its children are enabled. The child win¬ 
dows are not physically changed in any way, but because of the hierarchical relationship, 
their display characteristics are changed in practice. 

Ownership 

Ownership is a relationship among windows that is independent of the parent-child re¬ 
lationship. Any window can have an owner window. A window may have a parent and 
an owner; these are not necessarily the same window. Ownership is a linkage established 
between windows so that they may perform tasks in a coordinated manner. Windows 
that are owned notify their owners of significant events, such as when the window is 
dragged to a new location. In another example, the WM_MENUSELECT message is sent from 
a menu window to its owner when a menu item is selected. Usually, ownership is a rela¬ 
tionship established between a main window and its associated control windows. These 
control windows are such things as the titlebar, the min-max buttons, and the menu bar. 
In this case, WM_C0NTR0L messages are sent from a control window to its owner. 

With the parent-child and ownership concepts established, you can now understand 
something that is often surprising to programmers new to the Presentation Manager ar¬ 
chitecture. The object that appears on the desktop that is normally thought of as the 
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application’s window is not a single entity. It is not a single window with special areas for 
titlebars, min-max buttons, and other controls. Instead, it is a group of windows that are 
related to each other by ownership. 

In fact, the client area, the area in which an application may draw or display infor¬ 
mation, is actually a child window of the frame window to which it belongs. Essentially, 
the frame window is the border window, or the root window, where all the other control 
windows are attached. 

Ownership is established when the window is created. WinCreateWindow specifies 
both a parent and an owner. Ownership can be changed through the WinSetOwner API 
entry. Menu windows have their ownership set based on their submenu hierarchy. 

The preregistered window classes are the following: 

WC_FRAME 

WCJVIENU 

WC_C0MB0B0X 

WC_BUTT0N 

WC_STATIC 

WC_ENTRYFIELD 

WC_LISTBOX 

WC_SCROLLBAR 

WC_TITLEBAR 

WC_MLE 

WC_SPINBUTTON 

WC_CONTAINER 

WC_SLIDER 

WC_VALUESET 

WC_N0TEB00K 

Windows related to each other by ownership must be created within the same thread. 
This means they must also have the same message queue. Owner relationships are not 
permitted between windows created by different threads. 

Because ownership does not depend on a parent-child relationship, a window that 
owns another does not necessarily have to be descendant from the same parent. Destroy¬ 
ing an owner window, therefore, does not inevitably destroy the window that it owned. 


Messages 

OS/2 is a true multitasking operating system. Because an application must share the key¬ 
board and mouse with other applications running simultaneously on a particular system, 
individual applications cannot have total control of these resources. Some means is nec¬ 
essary to share these system resources. Further, because several applications will often be 
running simultaneously, some means must be provided for the operating system to com¬ 
municate with them. Messages and message queues provide this means. 
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Messages are necessary to enable the concurrent running of applications and the shar¬ 
ing of the system devices. Messages are the means by which the various windows, the 
operating system, and the user notify each other of events. Remember, events are usually 
such things as keys being pressed or the mouse being clicked. Usually a message is sent to 
tell an application a certain event has occurred. Sometimes, the application may need to 
respond to this event, other times not. 

Messages have a structure defined in the include file PM WIN. H, which is included 
by the file OS2.H. The message structure is listed in the following code. You can see that 
it is not difficult to understand. A message is a collection of bytes defining a handle, a 
message index, parameters passed with the message, and the time and mouse position 
when the message was generated. 

The actual code that defines the message structure is as follows: 

typedef struct _QMSG /* qmsg */ 

{ 


HWND 

hwnd; 

ULONG 

msg; 

MPARAM 

mpl; 

MPARAM 

mp2; 

ULONG 

time; 

POINTL 

pti; 

ULONG 

reserved 


} QMSG; 

With a little thought, you can easily think of the possible sources of events that cause 
messages to be sent to applications. Mouse and keyboard events, such as clicking a titlebar 
or pressing and releasing keys, cause the operating system to send messages to the appro¬ 
priate application’s window. The operating system may also send messages to an applica¬ 
tion when, for example, the application needs to repaint the client area. As another ex¬ 
ample, a WM_TIMER message will be sent at regular intervals when a timer has been set by 
an application. Applications may communicate by sending messages to each other. An 
application may even define its own set of messages, in addition to those defined by the 
system, which it can use to communicate about events between its own windows. 

This list of possible sources can be used to formalize the types of messages. “User- 
initiated messages” are created when the user presses a key, makes a menu choice, or 
performs some similar action. “Application-initiated messages” are generated by a win¬ 
dow of an application when it must send a message to another window about an event or 
some necessary action. “System-initiated messages” occur as the result of a system event. 

A message is information, a request for information, or a request for an action to be 
carried out by an application. If all messages had to be acted on immediately by every 
application, efficient coordination among applications and system resources would be 
nearly impossible. The message queue provides a means for messages to be posted to 
applications for later processing. 




Chapter 2d OS/2 Application Window Fundamentals 


Every application that will be receiving and responding to messages must create a 
message queue. This is performed with a call to WinCreateMsgQueue. You do not need 
to know the details about the actual structure of a message queue. A message queue is a 
place the operating system uses to store the messages directed to an application. As you 
might guess, this involves a block of memory big enough to hold a certain number of 
messages. This size is set at the WinCreateMsgQueue call. The queue also has a priority 
system so that some messages are reordered to make their processing by the application 
more efficient. For example, WM_PAINT messages come after WM_SIZE messages, because 
you would not want to paint a window, resize it, and then paint it again. 

The application is responsible for retrieving messages from its message queue. In most 
applications, this task is performed in a loop. Each message is retrieved, then passed to 
the appropriate window within the application. In our following application, this is per¬ 
formed with these lines: 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

The while loop continues until a WM_QUIT message is received. Each message is re¬ 
trieved as a structure from the queue and then dispatched to the window. When each of 
these messages is retrieved, WinGetMsg returns a value of TRUE. When a WM_QUIT mes¬ 
sage is received, WinGetMsg returns a value of FALSE, and the loop exits. 

An application may use the line 
WinPeekMsg (hab, &qmsg, 0, 0, PM_NOREMOVE) 

to check whether a message is in the queue, although we do not use that call in our 
sample application here. This function call returns immediately without waiting for a 
message. This can be used during long processing times to ensure that message response 
time is not being delayed by time consuming calculations. The pseudocode for some¬ 
thing like this would read as follows: 

while (not done doing very long spreadsheet recalculation) 

{ 

do recalculate the next column 

while (WinPeekMsg (hab, &qmsg, 0, 0, PM_ REMO VE)) 

WinDispatchMsg (hab, &qmsg) 

} 

If the message queue is empty, the operating system will cause processing for the 
message loop to cease until a new message appears in the queue. This allows more effi¬ 
cient use of the processor and its facilities. 

An application may have several windows, but only one message queue is needed. 
Each message retrieved from the queue is a structure as defined previously that contains, 
among other things, the handle to the window to which the message belongs. 
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Messages are generally posted to the queue and processed in a first-in and first-out 
order. An application, though, may search for specific messages in the queue and at other 
times ignore whole classes of messages. This enables you to give your application consid¬ 
erable flexibility in responding to the messages posted to it. 

The Window Procedure 

The last thing you must understand before we can get to the sample code is the operation 
of the window procedure. The window procedure is a function that receives and pro¬ 
cesses the messages for an application. A basic application will often have only a single 
window procedure, although some more complex applications will have many. 

Windows are defined in terms of window classes. Each window class has its own 
window procedure. Every instance of a window of that class will use that window proce¬ 
dure to process its messages. In our following SKELETON example, the window class is 
“CLIENT,” and its associated window procedure is the function ClientWndProc. This 
association is made with the function call WinRegisterClass. The call appears as 
follows: 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 

Notice that two of the parameters are the name of the class and the name of a win¬ 
dow procedure. Here, we have registered a private window class. Messages that this pri¬ 
vate window class receives will always be processed by the window procedure 
ClientWndProc. Now, take a look at the code for the window procedure ClientWndProc. 
Looking at the code, it appears that ClientWndProc responds to only two messages, 
WM_PAINT and WM_ERASEBACKGROUND. A window procedure, however, cannot ignore any 
message sent to it. This, however, does not mean an application must define a response 
for every message it may receive. Look again at the “switch” statement in the window 
procedure. Besides the WM_PAINT and WM_ERASEBACKGROUND cases, it also has a default 
case. This default case sets a variable signifying the message was not processed. Outside 
the switch statement are these lines: 

if (IbHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 

The function WinDefWindowProc passes the message back to the operating system 
for processing. This call must be made for every message for which the window proce¬ 
dure does not provide its own processing. WinDefWindowProc performs all default pro¬ 
cessing for the window. 
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Window Procedures Return Values 

Every message processed must return the proper value defined for it. For instance, in the 
window procedure ClientWndProc, the processing for the message to erase the background 
is performed with these lines: 

case WM_ERASEBACKGROUND: 

mReturn = MRFR0ML0NG(1L); 
break; 

This causes the window procedure to return the long integer value of 1 every time it 
receives a WM_ERASEBACKGROUND message. This causes the area inside the frame to be 
repainted. If a zero, is returned, the system will not repaint the area. 

Later, after you have successfully compiled and executed the application, you might 
try deliberately returning an incorrect value. For example, try changing the return value 
to 0. Notice that the background is never repainted. The portion of the screen within the 
frame when it was first created remains there even when the window is moved. 

SKELETON Application 

We wrote the SKELETON application to do two things. One is to illustrate the basic 
components of a PM application. The other is to provide you a framework with which 
you can begin building your applications. If you have never written applications for the 
OS/2 PM environment, we suggest you spend some time studying each of these compo¬ 
nent files. The thorough knowledge you gain with these will save you much guesswork 
later. First, we will describe the components of the SKELETON application; then, we 
will work through the process of building the application. 

Component Files 

Many programming languages and environments have a scheme in which multiple mod¬ 
ules are linked. OS/2 PM applications also follow that model. The components that make 
up a PM application, though, are more than additional code modules. Some are com¬ 
piled programming code, but others are files that contain instructions for the disposition 
of the code in memory at runtime. Still others are bitmaps that define the appearance of 
the application’s icon. These different components require different compilers and link¬ 
ers for them to be fitted together as a working executable file. Each of these components 
is eventually bound into a single executable file, but this is not a linear process. It requires 
a number of different steps. 
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For example, the component files for the SKELETON application are as follows: 

SKELETON.C 
SKELETON.H 
SKELETON.RC 
SKELETON.DEF 
SKELETON.ICO 

Each of the files that is readable by humans is listed and discussed in the following 
sections. 


SKELETON.C 

This file contains the application code to create and destroy the window that appears on 
the user’s desktop. Here, we have used only a single C module for all the code for our 
application. Complex OS/2 2.0 programs may have many dozens of modules. This C 
file also defines the “window procedure” for the SKELETON application. This window 
procedure, in turn, defines the messages to which the application will process internally. 
The behavior of this code is described in detail as follows: 


/* 


Skeleton Program 
Chapter 2 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#define INCL_GPI 
#include <os2.h> 

#include 11 skeleton. h" 

#include "..\common\about.h" 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 

HAB hab; 

HWND hWndFrame, 
hWndClient; 

CHAR szTitle[64]; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | FCF_IC 0 N | 

FCF_SIZEBORDER | FCF_MINMAX | FCF_MENU | 
FCF_SHELLPOSITION | FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 
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hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, (PFNWP)ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

HPS hps; 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinEndPaint (hps); 
break; 

case WM_ERASEBACKGROUND: 
mReturn = MRFROMLONG(1L); 
break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

default: 

bHandled = FALSE; 
break; 

} 
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if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 

} 

Understanding the Application Code 

Two files together make up the applications code: the C code file SKELETON.C and its 
associated include file SKELETON.H. 

The application must also include OS2.H. Look at the first lines of code in 
SKELETON.C to see the preprocessor commands, as follows: 

#define INCL_WIN 
#define INCL_GPI 
#include <os2.h> 

OS2.H is the standard highest level OS2 SDK file that includes all the other header 
files required. Because we don’t want all the possible header files included, we use INCL_WIN 
and INCL_GPI to include the Win... and Gpi... header files. This practice is used to de¬ 
crease the number of header files, which speeds compile time. We could have made this 
even more efficient in our example by specifically saying which parts of Win., and Gpi... 
API we wanted. For example, INCL_GPIREGIONS includes only the API entry points con¬ 
cerned with Gpi region functions. 

We suggest you take a look at the text for the OS2.H header file. This file is repro¬ 
duced here so that you can see how it is organized. It’s important to immediately get under 
the hood of OS/2 2.1 and any other system you are working with. Looking at any avail¬ 
able information about internal code will help you better understand and program for 
the operating system. A table of the define statements you can use to include only certain 
parts of the header files is listed at the end of this chapter. 

I*************************** Module Header *************************\ 

* * 

* Copyright 1987 - 1992 IBM Corporation * 

* * 

* Module Name: 0S2.H * 

* * 

* This is the top level include file that includes all the files \ 

* 

* necessary for writing an OS/2 application. * 

* 

y********************************************************************/ 
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#ifdef _IBMC_ 

#pragma checkout( suspend ) 

#ifndef _CHKHDR_ 

#pragma checkout( suspend ) 

#endif 

#pragma checkout( resume ) 

#endif 

#ifndef _0S2_H_ 

#define _0S2_H_ 

#define 0S2_INCLUDED 

/* Common definitions */ 

#include <os2def.h> 

/* OS/2 Base Include File */ 

#ifndef INCL_NOBASEAPI 
#include <bse.h> 

#endif /* INCL_NOBASEAPI */ 

/* OS/2 Presentation Manager Include File */ 

#ifndef INCL_NOPMAPI 
#include <pm.h> 

#endif /* INCL_NOPMAPI */ 

#endif /*_0S2_*/ 

#ifdef _IBMC_ 

#pragma checkout( suspend ) 

#ifndef _CHKHDR_ 

#pragma checkout( resume ) 

#endif 

#pragma checkout( resume ) 

#endif 

You can see there is little that’s mysterious about this file. It makes certain defines 
and includes a number of other include files. We suggest you use a text editor to open up 
some of the other important system include files. While on the subject of windows, look 
inside the file PMWIN.H. If you have a compiler or development kit for OS/2 installed 
on your system, PMWIN.H should be located in a directory with other include files for 
OS/2. 


The Main Procedure 

The Main Procedure for most PM applications will be similar to that listed here for the 
SKELETON application. In general, the main procedure for OS/2 2.1 applications per¬ 
forms three tasks in the following order: 
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1. Creates a window and message queue for the application. 

2. Processes messages destined for the window in a loop. 

3. Destroys the window and message queue when the loop ends, then exits. 

Creating the Application Window 

The SKELETON application window is created when the function WinCreateStdWindow 
is called. You can see from inspecting the code that some other things are performed before 
this function is called. These prepare for the creation of the window. 

Two things must always be done before the application’s window can be created: 
obtain a handle to an anchor block and create a message queue. 

Winlnitialize must be the first Presentation Manager call made by any thread that 
uses the Presentation Manager facilities. If you are reading closely, the word “thread” may 
seem odd. You may have expected the word “application” instead. Most applications have 
a single thread, a single line of execution. OS/2, however, allows applications to have many 
simultaneous lines of execution. These are called threads. Each of these threads must 
establish their own anchor block if they will be using facilities within Presentation Man¬ 
ager. It is possible one of the threads in your application may have no need of PM ser¬ 
vices. Multiple threaded applications are discussed in greater detail in Chapter 12, “Threads 
and Semaphores.” 

SKELETON calls Winlnitialize immediately after declaring some variables and 
before any other processing. 

hab = Winlnitialize (0); 

Winlnitialize takes a single parameter that must always be 0. This parameter indi¬ 
cates that all the messages for the window will initially be available for processing by the 
application. Winlnitialize returns a handle to an anchor block. 

You can think of the function WinTerminate as the function that corresponds to 
Winlnitialize. Notice that SKELETON makes a call to WinTerminate as the last 
call in the code to a Presentation Manager API entry. WinTerminate ends an applica¬ 
tion’s use of Presentation Manager facilities and releases all the associated resources. 
Notice also that SKELETON destroys all the windows and message queues before 
calling WinTerminate. If the services of PM are terminated before all these things are 
released, return values from the call to WinTerminate and those of subsequent calls are 
indeterminate. 
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Message Queues 

The message queue is created for the application when it calls the function 
WinCreateMsgQueue. This is done with the following line: 

hmq = WinCreateMsgQueue (hab, 0); 

The input parameters for our example are the handle to the anchor block returned 
by Win Initialize and a size for the message queue. This call must be made after the 
call toWinlnitialize, but before any other Presentation Manager functions are called. 
One message queue serves all the windows in a thread. In this example, we have only one 
window and one thread, so this is easy to sort out. 

The function WinCreateMsgQueue returns a handle that can be used by WinGetMsg 
to retrieve messages from the queue. In SKELETON, this handle is assigned to the vari¬ 
able hmq. Notice, however, that the call that SKELETON makes to function WinGetMsg 
uses the handle to the anchor block. 

The size of the message queue can be specified by the application. The second pa¬ 
rameter in the call to WinCreateMsgQueue in our SKELETON application is 0. This 
does not specify a queue of length zero; it causes a queue of the default size to be created. 
The system default queue size has a length that allows for 10 messages. 

As the application runs, the operating system receives all the input from the mouse 
and keyboard into its own message queue. It then converts these input events into mes¬ 
sages and posts them to the proper application message queues. The application, during 
its processing, retrieves the messages from its queue and processes them. For the SKEL¬ 
ETON example, the messages are processed for only one window with the ClientWndProc 
window procedure. Several windows, however, may be assigned to one message queue, 
though we have not done that here. 

You should also know that if messages within the queue would be redundant, the 
operating system may update the message queue to shorten it. Adding messages to a 
message queue is called posting a message. The operating system does not post messages to 
a queue and then ignore them. For example, if posting a new message would place more 
than one WM_PAINT message in the queue, the operating system will combine the regions 
described by the paint messages into a single region. It then posts a WM_PAINT message 
with that larger region to the queue. 

Before an application terminates, its message queues must be destroyed. This is 
accomplished by calling the function WinDestroyMsgQueue. The input parameter is the 
handle to the message queue returned by WinCreateMsgQueue at the start of 
the program. 
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Registering a Class 

After getting a handle to an anchor block and creating a message queue, the SKELETON 
application registers a private window class for CLIENT. We have used the name 
CLIENT, and this is completely arbitrary. The name CLIENT is associated in the 
SKELETON code with the window procedure ClientWndProc. All windows created 
with the class name of CLIENT in SKELETON would use the ClientWndProc win¬ 
dow procedure. 

Loading a String 

WinLoadString loads a string resource. In SKELETON.C, this function is called with 
this line: 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

The parameter ID_APPNAME identifies the string resource to be loaded. This string 
resource is defined in the resource file SKELETON.RC with this line: 

ID_APPNAME "Skeleton" 

Take a quick look at the resource file for comparison. 

This resource string is loaded into the buffer szTitle that is defined at the begin¬ 
ning of the code as 64 characters. The maximum length of this buffer is indicated with 
the call sizeof (szTitle) used as one ofWinLoadString’s parameters. WinLoadString 
will append a terminating 0 character to the string. 

You could hard code this string value into the application rather than retrieve it as a 
string resource. This is usually a bad practice. Placing titles, button names, and other similar 
strings in the resource file gives you several advantages. It saves redundantly hard coding 
the same values in many places in your application. It keeps these string values grouped 
together, making them easier to revise and compare. If your application should ever have 
to be translated to another language, it makes it far easier for your application to be local¬ 
ized. 


SKELETON. H 

Only a single define statement is used in this example. Some examples listed later in the 
book, however, have large header files. 


/* 


Skeleton Header File 


*7 


#define ID APPNAME 1 
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This include file does no more than define the constant ID_APPNAME. This constant 
is used both in the SKELETON.C code file and in the SKELETON.RC resource file. 

SKELETON.RC 

The resource script file for this application defines the application name, associates it with 
the skeleton icon, and defines some other characteristics described in more detail in sub¬ 
sequent text. Like the application code, it is an ASCII text file. It can be created by using 
any ASCII text editor. 

The resource script file does have many syntactic similarities to C code, for instance 
the use of #include statements, but it is not C code. The resource file requires its own 
resource compiler to make the file useful in the application’s executable code. A resource 
compiler is provided with the IBM Developer’s Toolkit for OS/2 2.1. Resource compil¬ 
ers are also often provided with other vendors’ development toolkits. 

After a syntactically correct resource script file has been created, it is used as input to 
the resource compiler. The output from that compiler will be a file with the extension 
RES. This file is not readable by humans. It will be bound into the application’s execut¬ 
able. The resources it defines, such as strings and dialog box definitions, are then avail¬ 
able for the application to use when it is running. 

Many application elements may be defined in an application’s resource file, includ¬ 
ing the following: 

Fonts Fonts may be edited and created with the Font Editor, 

which comes as a part of the OS/2 2.1 development 
toolkit. 

Icons These include mouse pointers and bitmaps, as well as 

window icons. These may be created and edited by 
using the Icon Editor, which also comes with the 
toolkit. 

Menus Menus are also defined in the resource file. 

String Tables Tables of text strings can be defined for the 

application’s use. 

Accelerator Tables Accelerator keys enable your users to access an action 

or menu choice without clicking each menu choice, 
for example, using Alt-H to cause general help to pop 
up. Tables to define these keys are created in the 
resource file. 
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Dialog Templates Dialog boxes are frequently created in the form of 

templates. These may be created using the Dialog Box 
Editor, which comes with the OS/2 development 
toolkit. Often these dialog box templates are included 
in the resource file using the #include keyword. 
Window Templates Window templates may also be created using the 
dialog editor and made available to the application 
through the resource file. 

The resource file for the SKELETON example defines only an icon and a string table. 
Other examples, later in the book, define considerably more. 

Notice that our sample resource file also begins with the following statement: 

#include <os2.h> 

This is frequently necessary because many of the symbolic names used in resource 
script files may actually be defined in the C include file. This may seem odd—mixing of 
file types—so do not be confused. Although it is generally associated with C code, the 
include file is often processed by a preprocessor before the compiler even looks at it. That 
is the case here for the resource compiler as well. The include file OS2.H is also pro¬ 
cessed by a preprocessor for use in the resource file before the resource compiler begins 
working with the resource file. 

Notice also that our sample file also uses another C include file, SKELETON.H. This 
is a file that is also used by the application code. It defines ID_APPNAME to have the value 
of 1. Again, this is another arbitrary value. The next line in the file is as follows: 

ICON ID_APPNAME SKELETON.ICO 

The ICON keyword designates the resource identifier ID_APPNAME —which follows 
ICON—as an icon resource. In every case, the symbolic name that follows the keyword 
must be defined as an integer constant. This definition for our sample here is accom¬ 
plished in the include file SKELETON.H. 

/* . 

Skeleton Resource File 
Chapter 2 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

. */ 


#include <os2.h> 
#include "skeleton.h 


ICON ID APPNAME SKELETON.ICO 
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STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Skeleton Application" 

END 

MENU ID_APPNAME 

{ 

MENUITEM "-About", IDM_AB0UT 

} 

rcinclude ..\common\about.dig 

After the icon definition, a string table is defined. This is signaled by the keyword 
STRINGTABLE. String tables are used to incorporate text into the applications executable. 
This text is then available for use in many different ways including menu bars, error 
messages, and so forth. 

The string table for the SKELETON application has only a single entry. The string 
“Skeleton” is associated with the identifier ID_APPNAME that was defined in the include 
file SKELETON.H. Notice, the string table is delimited by the keywords BEGIN and END. 
By the way, the curly brackets { and } can be substituted for BEGIN and END. 

Compiling SKELTON.RC 

The resource file must be compiled before it can be bound to the executable file. This 
compilation is accomplished with the resource compiler. A resource compiler is provided 
with the OS/2 2.1 toolkit. Resource compilers may also be provided by a third-party 
compiler vendor. 

If you are using an integrated development environment, like that supplied by Borland, 
this compilation may be handled automatically. Although you do not generally compile 
the resource file by hand, take the time to do that now to get some practice. For example, 
be sure the resource compiler is in the same directory as SKELETON.RC, or that it is in 
a directory that’s in your path statement. Then, on the command line at an OS/2 2.1 
prompt, enter this command: 

RC -h 

The output you see should be similar to this: 

Operating System/2 Resource Compiler 
Version 2.00.000 Nov 9 1991 
Copyright IBM Corporation 1988-1991 
Copyright Microsoft Corp. 1985-1991 
All rights reserved. 

Usage: rc [<options>] <.RC input file> [<.EXE output file>] 
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-d defname - Preprocessor define 
-Ddefname - Preprocessor define 

-i - Include file path 

-r - Create .res file 

-p - pack - 386 resources will not cross 64K boundarys 

-cp cp | lb,tb,... - DBCS codepage or lead/trail byte info. 

-h - Access Help 

Environment variables: 

DBCS=cp | lb,tb,.. . 

TMP=temporary file path 
TEMP=temporary file path 
INCLUDE=include file path 

You can see that using the - h option causes the resource compiler to write out the 
options available to you. Now, enter this command: 

RC SKELETON.RC 

Because no executable name is provided, the resource script file will be converted to 
its compiled .RES version. Your output should look similar to this: 

Operating System/2 Resource Compiler 
Version 2.00.000 Nov 9 1991 
Copyright IBM Corporation 1988-1991 
Copyright Microsoft Corp. 1985-1991 
All rights reserved. 


Creating binary resource file skeleton.RES 

RC: RCPP -E -D RC_INVOKED -f skeleton.rc -ef c:\os2\RCPP.ERR -I 

d:\watcom\h\0S2 -I d:\watcom\h 

skeleton.rc.. 

Writing resources to OS/2 v2.0 Linear .EXE file 
Writing 1 DEMAND resource object(s) 

Writing: 1056 bytes in 1 page(s) 

1.1 (1010 bytes) 

1.5 (42 bytes) 

Writing Extended Attributes: Default Icon 
Writing Extended Attributes: Checksum 

Look in the directory that contained the resource script file. You should see a file 
with an .RES extension with a recent file creation time. This .RES file contains the com¬ 
piled resource that would be bound to the application s executable file. 
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SKELETON.DEF 

Presentation Manager applications need a module definition file. This file is used for 
creating application programs and for creating Dynamic Link Libraries (DLLs). For our 
example, we are interested in the file’s use for creating PM programs. This file is utilized 
at the linking stage when building your application to define some specifics about the 
disposition of your code when it is run. 

This file is an ASCII text file with the extension .DEF. It can be created by using any 
text editor. The syntax for module definition files contains a limited number of keywords. 
Before we list all those, take a look at the module definition file for the SKELETON 
sample. It contains these lines: 

NAME SKELETON WINDOWAPI 

DESCRIPTION 'Skeleton Program Blain, Delimon, & English, 1993' 
STACKSIZE 32768 

EXPORTS ClientWndProc 

AboutDlgProc 

You can see at a glance that each line begins with a keyword followed by a value or a 
string. The first line, which begins with the keyword NAME, assigns the module the name 
SKELETON. This is followed by the keyword WINDOWAPI, which designates this appli¬ 
cation is a full Presentation Manager application. It does not simply run in a text win¬ 
dow or full-screen session. 

The next line begins with the keyword DESCRIPTION. The string that follows it be¬ 
comes a part of the application’s executable. You can take a look at this string’s location 
in the actual executable file by using a HEX editor. 

The line 

STACKSIZE 32768 

indicates that 32K of memory are to be set aside for use as the application’s stack. The 
recommended minimum stack size for Presentation Manager applications is 8K. Recall 
that the stack is the area in which local variables along with passed parameters are kept. 

The last line in our sample module definition file begins with the keyword EXPORTS. 
This keyword is not needed here because we are generating an executable file. OS/2 2.1 
is able to find ClientWndProc because its address was given during the call to 
WinRegisterClass. The function does not need to be exported as it needed to be in 
prior versions of OS/2. The EXPORT keyword is now used to allow functions in DLLs to 
be resoved by the loader when the DLL is loaded. As a result, it is necessary for DLLs, 
but it is not required for executables. The string that follows EXPORTS is the name of the 
windows procedure used by SKELETON. Look in the code SKELETON.C to see where 
ClientWndProc is defined. Notice that no function header is in SKELETON.C. 
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ClientWndProc is called by the operating system with the messages that it should 
process for its associated window. 

SKELETON.ICO 

This is a bitmap used as the application’s icon. It was created by ICONEDIT. ICONEDIT 
is provided with OS/2, but there are many different third-party resource editors you could 
use. Notice that we refer to the icon as a “resource.” This is the customary terminology. 
Icons, bitmaps, and cursors are frequently referred to as resources for the application. Do 
not confuse this with the resource file that has an entirely separate use. Icons, cursors, 
and bitmaps are, of course, displayed. Resource files are used to provide things such as 
string tables, accelerator tables, and more to the executable code. 


Using the SKELETON Application 

Double-click the SKELETON icon to start the application. The application window for 
the SKELETON application should appear as in Figure 2.3. 


Figure 2.3. 

The SKELETON 
application window. 


]3l 


1 Skeleton Application 


About 


Beyond adding the SKELETON application to a window and double-clicking to open 
its main window, there is little more that can be done with it. It is important, however, 
as a basis for learning. Consider each of the features that are a part of the main window, 
such things as the titlebar, the system menu, and others. Compare these features with 
that part of the code that caused them to be included with the frame window. You may 
even try adding some additional capability. For example, you might include the frame 
control flag for a vertical scroll bar and then rebuild the application s executable file. 

You may want to use the code for the SKELETON application as a basis for further 
experimentation. Spend some time adding features or changing window styles to famil¬ 
iarize yourself with programming for OS/2. 




Chapter JL OS/2 Application Window Fundamentals 


Useful Window Reference Material 

Some of the common functions, flags, and identifiers used in conjunction with windows 
under Presentation Manager are listed in the following text. This is not an exhaustive list 
by any means, because you can quickly see that the OS/2 technical documentation is much 
larger—so much larger, in fact, that it is sometimes difficult for a programmer new to 
OS/2 to know where to begin. We, therefore, have listed some of the more common items 
of interest here. Familiarizing yourself with these will help you with future application 
development. 

Common Window Functions 

The following is a list of commonly useful window functions. These are grouped by their 
general area of use. Each is followed by a short description; for a detailed reference about 
each function, please refer to the OS/2 2.0 Technical Library. 

Creation and Destruction of Windows 

WinCreateWIndow 

Use this function to create a window. It has a more general form than 
WinCreateStdWindow. 

WinCreateStdWindow 

Use this function to create one of OS/2 5 s standard windows. 

WinDestroyWindow 

Destroys a window. All the window’s child windows are also destroyed. Resources used 
by the windows are also freed. 

Visibility of Windows 

WinlsWindowShowing 

Use this function to find out whether any part of a window is currently displayed. This 
function returns TRUE only if part of the window is physically displayed, not if the win¬ 
dow is simply marked visible by the operating system. 


WinShowWindow 

Use this function to change the state of visibility for a window. 
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Sizing and Positioning of Windows 

WinSetWindowP os 

Use this function to position a window on the display. The window is positioned in terms 
of its parent’s lower-left corner. This function also has a number of options for such things 
as hiding, maximizing, deactivating, and other similar operations. 

WinQueryWindowPos 

Use this function to get the size and position of a particular window. 

WinGetMinPosition 

Use this function in conjunction with WinSetWindowPos. WinGetMinPosition returns 
the available spot to which a window may be minimized. Then use WinSetWindowPos to 
minimize the window. 


WinSetMultWindowPos 

Use this function to change the position of several windows with a single function call. 
All windows to be repositioned with this call must have the same parent. 

WinQueryWindowRect 

Use this function to obtain the coordinates of a window rectangle. These are measured 
in terms of the window itself. The lower-left has the value pair 0,0. The upper-right is 
measured in terms of window coordinates. This effectively yields the window coordinates. 

WinMapWindowPoints 

Call this function to obtain the coordinates of a window mapped relative to the coordi¬ 
nates of another window. 


Relationships Among Windows 

WinSetParent 

Use this function to change the parent window of a window. The descendent of a win¬ 
dow cannot be made the parent of a window. 

WinQueryWIndow 

Use this function to return the handle to a window that has one of the following rela¬ 
tionships to the input window handle: 
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Next window in the Z-order 
Previous window in the Z-order 
Top child window 
Bottom child window 
Window owner 
Window parent 

Z-order is simply the relative layer in which windows lie on the desktop. Window 
handles with other more complicated relationships may also be obtained with this func¬ 
tion. 

WlnSetOwner 

Use this function to change the owner of a window. You may use the input constant 
NULLHANDLE to mark a window as “disowned.” 

WinBeginEnumWindows 

Use this function to enumerate the child windows for a window. Use in conjunction with 
WinGetNextWindow call to obtain the handles to the child windows in z-order. 

WinGetNextWindow 

See WinBeginEnumWindows in preceding text. 

WinEndEnumWindows 

Ends the child window enumeration process. 


WinlsChild 

Use this function to determine if one window is the child of another. 


WinQueryDesktopWindow 

Use this function to obtain the handle to the desktop window. You may also use the 
constant HWND_DESKTOP as input for many window functions, rather than explicitly ob¬ 
taining this handle. 


WinQueryO bj ectWindow 

Use this function to obtain the handle to the desktop object window. 
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WinWindowFromlD 

Use this function to get the handle of a child window using a specific ID, which was 
assigned at creation. 


WinWindowFromPoint 

Use this function to get the handle of a window that is below a specific point and a de¬ 
scended window of the input window handle. 

WinMultWindowFromlDs 

Use this function to obtain an array of handles to all the child windows of a specified 
window. 

Window Input Functions 

WinQueryActiveWindow 

Use this function to obtain the handle to the active window. 

WinSetActiveWindow 

Use this function to make a frame window the active window. 


WinQueryFocus 

Use this function to obtain the handle to the window that has the focus. 


WinSetFocus 

Use this function to give the specified window the input focus. 


WinQuerySysModalWindow 

Use this function to obtain the handle to the current system modal window. Modal win¬ 
dows force the user to complete processing within that window before continuing. 


WinSetSysModalWindow 

Use this function to make a window a system-modal window. Other windows are not 
alerted when the system-modal state is entered. You may also use this function to end the 
system-modal state. A system modal window prevents interaction with other windows 
on the desktop. 
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WinStartApp 

Use this function to start another application from within a window. A handle to the 
application started is returned to the window. The message WM_APPTERMINATENOTIFY is 
posted to the window’s message queue when the application terminates. 


WinT er minate 

When a thread within your application has finished processing, use this function to ter¬ 
minate its use of Presentation Manager’s facilities. All windows and message queues cre¬ 
ated by the thread must be destroyed first, before calling WinTerminate. 


WinT erminateApp 

Use this function to terminate an application that was started from within a window using 
the WinStartApp function. This function must be called from within the same process 
that called WinStartApp. 

Window Word Data 

WinQueryWindowUShort 

Use this function in conjunction with an input index to obtain a specific value from the 
window word’s memory of a window. You may obtain such things as the y coordinate to 
which the window is minimized, or the window’s ID. 


WinSetWindowUShort 

This function is similar to WinQueryWindowUShort, except it is used to set a value within 
the window word’s memory. 


WinQueryWindowULong 

This function is similar to WinQueryWindowUShort in use. Utilize it to obtain values for 
such things as window style or default pushbutton for a dialog. 

WinSetWindowULong 

This function is similar to WinQueryWindowULong, except it is used to set a value within 
the window word’s memory. 


WinQueryWindowPtx 

Use this function to obtain a pointer value from the window word’s memory. 
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WinSetWindowBits 

Use this function to set individual bits within a window word’s memory. This function 
can also set bits in the form of a mask. 

Standard Window Classes 

Window classes may be public or private. Public window classes have a re-entrant win¬ 
dow procedure that resides in a DLL. Public window classes may be used by any process 
to create windows. OS/2 2.1 provides a number of public window classes, listed in the 
following text. Private window classes are registered by individual applications for their 
own use. The window procedure resides either in the application code or in a DLL of the 
application. 

The standard window classes are as follows: 


WC_BUTTON 

Defines buttons and boxes for the user to click with 
the mouse. 

WC_CONTAINER 

Groups objects in a logical manner. 

WC_ENTRYFIELD 

Single line of text, editable by the user. 

WCJFRAME 

Window class that generally contains child windows 
of the other classes listed here. 

WC_LISTBOX 

Contains a list of text items from which the user 
may make a selection. 

WC_MENU 

Presents a list of items to be used as a menu. 
Generally provides a command interface for the user 
to utilize with the application. 

WCJSfOTEBOOK 

Presents a control displayed as a stack of pages. 

WC_SCROLLBAR 

Enables the user to scroll the contents of another 
window associated with the scroll bar. 

WC_SLIDER 

Presents a control that the user may utilize to select 
among a range of values. 

WC_SPINBUTTON 

Presents the user with a spinner control. 

WC_STATIC 

Window class that displays items with which no 
interaction is needed. 

WC_TITLEBAR 

Presents the user with a title or caption. It also 
enables the user to move its owner. 

WCJVALUESET 

Presents a set of mutually exclusive values the user 
may select. It is similar to a radio button control. 
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Class Styles 

Every window class may have one or more class styles. These indicate to the system which 
characteristics the window will have when created. Class styles for private window classes 
are set when the class is registered. After a class is registered, the application cannot change 
its style. Notice that these characteristics apply to a “class” of windows. Characteristics, 
within some limitations, may be set for individual windows using the window styles, listed 
in a following section. 


CS_CLIPCHILDREN 

CS_CLIPSIBLINGS 

CS.FRAME 

CS_HITTEST 

CS_MO VEN OTIFY 

CS_PARENT CLIP 

CS_SAVEBITS 


CS_SIZEREDRAW 


CS_S YN CPAINT 


Prevents a window from painting over its 
children. This is useful in working with dialogs. 
Use this to prevent sibling windows from 
painting over each other. 

Use this to designate the window as a frame 
window. 

The window will receive HITTEST messages 
whenever the mouse is moved in the window. 
The window will receive WM_MOVE messages 
whenever the window is moved. 

Prevents child window from painting on its 
parent window. 

This causes the system to save the area under the 
window as a bitmap. When the window is 
hidden or moved, the image is replaced from 
memory, rather than repainted by the applica¬ 
tion. This can improve performance, at the 
expense of memory. 

This causes the window to be invalidated and 
to receive a WM_PAINT message when it is 
resized. This forces the whole area to be redrawn, 
rather than only a part. 

This forces WM_PAINT messages to be sent to 
the window any time part of the window be¬ 
comes invalid. Otherwise, the window would 
receive WM_PAINT messages only when no 
other messages are waiting to be processed. 


Standard Window Styles 

Windows may have a number of different styles. Whereas class styles apply to every win¬ 
dow of a particular class, window styles apply to individual windows. The OS/2 operat¬ 
ing system has a number of styles that it provides for windows. The more common styles 
are listed here: 
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WS_CLIPCHILDREN 

WS_CLIPSIBLINGS 

WSJDISABLED 
WSJMAXIMIZED 
WS_MINIMIZED 
WS_PARENT CLIP 

WS_SAVEBITS 


WS_SYNCPAINT 


WS.VISIBLE 


The child windows descended from the window 
will not be painted over. 

Sibling windows of the window will not be 
painted over. 

This causes a window to reject input. 

The window is enlarged to its maximum size. 
The window is reduced to the size of an icon. 
The clip region of a window is extended to 
include the area of the parent window. 

This causes the system to save the area under the 
window as a bitmap. When the window is 
hidden or moved, the image is replaced from 
memory, rather than repainted by the applica¬ 
tion. This can speed performance, again at the 
expense of memory. 

This causes WM_PAINT messages to be sent to 
the window immediately after any part of it 
becomes invalid. 

This causes the window to be made visible. The 
window will be displayed if it can be. 


Dialog Manager Styles 

WS_GROUP In the case when the user may move from 

control to control in a dialog box by using the 
arrow keys, this value designates which control is 
the first control. 

WS_TABSTOP Each control that has WS_TABSTOP as a style 

will receive keyboard focus in turn as the user 
presses Tab. 


Frame Control Flags 

FCF_ACCELTABLE 

F CF_AUT OICON 


An accelerator table from the resource file 
will be loaded for this window; therefore, 
of course, one must be made available. 
This optimizes performance. When the 
operating system redraws iconized frames, 
the icon will be redrawn, but no 
WM_PAINT message will be sent to the 
application. 
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FCF_BORDER 

The window is drawn with a thin border. 

FCF_DLGBORDER 

The window is drawn with a standard 
border. 

FCF_HIDEBUTTON 

This includes a hide button as one of the 
frame controls. 

FCF_HIDEMAX 

This includes hide and maximize buttons 
with the frame controls. 

FCF_HORZSCROLL 

A horizontal scroll bar is created with the 
window. 

FCFJCON 

This causes an icon to be associated with 
the window. This is the icon displayed 
when the window is minimized. 

FCF_MAXBUTTON 

A maximize button is created with the 
window. 

FCF_MENU 

An application menu is created with the 
window. 

F CF_MINBUTT ON 

A minimize button is created with the 
window. 

FCF_MINMAX 

Minimize and maximize buttons are 
created with the window. 

FCF_NOBYTEALIGN 

When this flag is NOT set, optimiza¬ 
tions such as moving the window in 8 pel 
increments are performed. Setting the 
flag causes the optimizations not to be 
performed. 

FCF_NOMOVEWITHOWNER 

The window that has this flag set will not 
be moved when its owner is moved. 

FCF_SHELLPOSITION 

When the window is created, its size and 
position will be determined by the OS/2 
shell. The application does not have to 
explicitly state these size and position 
values. 

FCF_SIZEBORDER 

A sizing border is created with the 
window. 

FCF_STANDARD 

This frame control flag is the equivalent of 
a number of the other frame control ORed 
together. As its name implies, this is the 
single frame control flag that will be used 
most often. It is the equivalent of the 
following flags all ORed together: 

FCF_ACCELTABLE 

FCFJCON 
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FCF_MAXBUTTON 

FCF_MENU 

FCF_MINBUTTON 

FCF_SHELLPOSITION 

F CF_S IZEB ORDER 

FCF_SYSMENU 

FCF_SYSMODAL 

FCF__TASKLIST 

FCF_TITLEBAR 

FCF_SYSMENU 

FCF_TASKLIST 


FCF_TITLEBAR 
F CF_ VERT S CRO LL 


A system menu is created with the 
window. 

The flag causes the program title and the 
frame window text to be concatenated. 
This concatenated text is used as the 
window title and in the task list. 

A titlebar is created with the window. 

A vertical scroll bar is created with the 
window. 


Frame Contol Identifiers 


These are the system defined identifiers 

FID_CLIENT 

FID_HORZSCROLL 

FID_MENU 

FID_MINMAX 

FID_SYSMENU 

FID_TITLEBAR 

FI D_ VERTS CRO LL 


given to control windows: 

Client window. 

Florizontal scroll bar. 

Menu. 

Minimize and maximize buttons. 
System menu. 

Titlebar. 

Vertical scroll bar. 


Predefined Window Handles 

Certain window handles must be accessed often within Presentation Manager code. A 
number of constants for specific windows are in the following list. The handles could be 
explicitly obtained by making a function call, but using these constants is more conve¬ 
nient. 


FiWNDJDESKTOP 

HWND_OBJECT 

HWND_TOP 

HWND_BOTTOM 


Desktop window. 
Desktop object window. 
Extreme top window. 
Extreme bottom window. 
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Includes 

Use the following defines within your code to include only certain portions of the OS/2 
header files. 


Atom manager 

IN CL_WINAT OM 

Button controls 

INCL_WINBUTTONS 

Clipboard manager 

INCLJWINCLIPBOARD 

Country support 

IN CL_WIN COUNTRY 

DBCS window manager definition 

INCL_NLS 

Desktop API 

INCL_WINDESKTOP 

Dialog boxes 

INCL_WINDIALOGS 

Entry Fields 

INCL_WINENTRYFIELDS 

Error code definitions 

INCL_WINERRORS 

Frame controls 

INCL_WINFRAMECTLS 

Frame manager 

INCL_WINFRAMEMGR 

General window management 

INCL_WINWINDOWMGR 

Heap manager 

INCL_WINHEAP 

Help manager definitions 

INCL_WINHELP 

Hook manager 

INCL_WINHOOKS 

Keyboard accelerators 

INCL_WINACCELERATORS 

Listbox controls 

INCL_WINLISTBOXES 

Load/Delete Library/Procedure 

IN CL_WINLOAD 

Menu controls 

INCL_WINMENUS 

Message management 

INCL_WINMESSAGEMGR 

Mouse and keyboard input 

INCL_WININPUT 

Mouse pointers 

INCL_WINPOINTERS 

Multiple line entry fields 

INCL_WINMLE 

Rectangle routines 

INCL_WINRECTANGLES 

Scroll bar controls 

INCL_WINSCROLLBARS 

Set error info API 

INCL_WINSEI 

Shell data 

INCL_WINSHELLDATA 

Shell program list API 

INCL_WINPROGRAMLIST 

Shell switch list API 

INCLWINSWITCHLIST 

Static controls 

INCL_WINSTATICS 

System values (and colors) 

INCL_WINSYS 

Text cursors 

INCL_WINCURSORS 

Thunk procedure API 

INCL_WINTHUNKAPI 

Timer routines 

INCL_WINTIMER 

WinTrackRectQ function 

IN CL_WINTRACKRECT 








Introduction 

The first window created by OS/2 at start-up is the window known as the desktop object 
window. The desktop object window serves as a base window for applications and system 
usage, but is never displayed. Because it can never become visible, none of its descen¬ 
dants can be visible. This object window, referred to as HWND_OBJECT, can be 
used as the parent and/or owner of any window that acts as a “server” 
window or that must be temporarily disconnected from its win¬ 
dow family tree without being destroyed. The identifer 
HWND_0BJ ECT can be used whenever the object window is used, 
or you can query the actual object window handle by using the 
eryObj ectWindow API: 
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HWND hWndObjectWindow = WinQueryObjectWindow (HWND_DESKTOP); 

The second window created by PM at start-up is the window known as the desktop 
window. This window is also known as the “workplace” window. This window serves as 
the base window for applications and is always visible. It is responsible for painting the 
screen background and serves as the parent of all top level windows. The desktop win¬ 
dow, referred to as HWND_DESKTOP, can be used as the parent and/or owner of any win¬ 
dow. The identifier HWND_DESKTOP can be used when the desktop window is used, or 
you can query the actual desktop window handle by using the WinQueryDesktopWindow 
API: 

HWND hWndDesktopWindow = WinQueryDesktopWindow (hAB, NULL); 

Windows created as children of HWND_OBJECT are called object windows. Windows 
created as children of HWND_DESKTOP are called top-level windows. All windows that your 
application creates are descendants of one of these two windows. 

The Family Tree 

All windows have both a parent and an owner window. These relationships establish how 
the window is drawn and how the window interacts with other windows. The most im¬ 
portant relationship in determining the appearance of a window is the parent-child rela¬ 
tionship. A child can never draw outside the boundary of its parent. Its coordinates are 
specified relative to the parent’s lower-left corner. All children with the same parent are 
called siblings. For example, the top-level window of all applications are children of the 
desktop window; therefore, all these top-level windows are also siblings of each other. 

Because it is possible for windows to overlap one another, there must be some de¬ 
fined order for how and when windows are drawn. Parent windows are always drawn 
before their children. Sibling windows are drawn based on what is called the Z-order of 
the windows. The Z-order is an ordering, or stacking, of the sibling windows. You can 
imagine the Z-order by picturing the windows from the side of the screen and seeing the 
sibling windows as being stacked from bottom to top. The top half of Figure 3.1 shows 
four overlapping sibling windows. The bottom half of the figure shows how they might 
appear from the side. The windows are drawn from bottom to top based on the Z-order. 

All windows created by an application define both a parent window and an owner 
window. The owner window can be NULL. After the windows have been created, it is 
possible to query the handle of the parent: 

HWND hWndParent = WinQueryWindow (hWndChild, QW_PARENT); 
the handle of the owner: 

HWND hWndOwner = WinQueryWindow (hWndOwnee, QW_0WNER); 
or the handle of any child with a given identifier (for example ID_CHILD): 
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HWND hWndChild = WinWindowFromID (hWndParent, ID_CHILD); 

You can also query the sibling windows in a sequence based on their Z-order. The 
extreme top child window can be queried: 

HWND hWndTopMostChild = WinQueryWindow (hWndParent, QW_T0P); 
or the extreme bottom child window can be queried: 

HWND hWndBottomMostChild = WinQueryWindow (hWndParent, QW_B0TT0M); 

Starting with the extreme top child window, you can query the child window below 
that window (in Z-order): 

HWND hWndNextChildBelow = WinQueryWindow (hWndChild, QW_NEXT); 

You can continue using the QW_NEXT parameter until the WinQueryWindow call re¬ 
turns zero, which indicates the extreme bottom window has been reached. Likewise, if 
you start with the extreme bottom child window, you can query the child window above 
that window (in Z-order): 

HWND hWndNextChildAbove = WinQueryWindow (hWndChild, QW__PREV); 

You can continue using the QW_PREV parameter until the WinQueryWindow call 
returns zero, which indicates the extreme top window has been reached. 


Figure 3.1. 

Z-order relationship of 
sibling windows. 
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It is also possible to enumerate all the siblings of a window one at a time within what 
is called a window enumeration loop. To start window enumeration, use the 
WinBeginEnumWindows function. This function will take a “snapshot” of the list of child 
windows for the specified window handle. Then use WinGetNextWindow to retrieve each 
child window. When you are through enumerating, call WinEndEnumWIndows to release 
the list of child windows. This method enumerates the windows in Z-order from extreme 
top to extreme bottom. 

The following function can be used to enumerate all the descendants of a window: 

VOID EnumerateDescendants (HWND hWndParent) 

{ 

HENUM hEnum; 

HWND hWndChild; 

hEnum = WinBeginEnumWindows (hWndParent); 

while ((hWndChild = WinGetNextWindow (hEnum)) != 0) 

{ 

EnumerateDescendants (hWndChild); 

> 

WinEndEnumWindows (hEnum); 
return; 

} 

To enumerate all windows in the system, call this function with HWND_DESKTOP: 

EnumerateDescendants (HWND_DESKTOP); 

To move a window in front of another sibling, you must change its Z-order. The 
Z-order of windows can be modified by calling WinSetWindowPos and by using the 
SWP_ZORDER flag: 

WinSetWindowPos (hWnd, hWndAfter, 0L, 0L, 0L, 0L, SWP_ZORDER); 

The window hWnd is positioned below hWndAfter. The predefined constants HWND_T0P 
and HWND_B0TT0M can be used to specify that the window be positioned at the top of the 
Z-order or the bottom of the Z-order. 

The parent and owner of a window are defined when a window is created. Both of 
these, however, can be changed at any time with the WinSetParent and WinSetOwner 
functions. Changing the parent causes the window’s position to change relative to the 
new parent. The WinSetParent API is used to change the parent of a particular window: 

BOOL bRedraw = TRUE; 

WinSetParent (hWndChild, hWndNewParent, bRedraw); 
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This will change the parent of hWndChild to be hWndNewParent. The bRedraw para¬ 
meter tells PM whether it should redraw the child window when the parent window is changed. 
You should set the bRedraw parameter to FALSE if the functions immediately following will 
cause either further changes in the window or the window to be painted. Changing the 
owner of a window changes the window that receives the notification messages from the child. 
The WinSetOwner API is used to change the owner of a particular window: 

WinSetOwner (hWndChild, hWndNewOwner); 

This will change the owner of hWndChild to be hWndNewOwner. All notification 
messages sent from hWndChild will then be sent to hWndNewOwner. 

If you have the window handle and want to determine whether that window is a 
descendant of a particular parent window, use the WinlsChild API: 

BOOL bChild = WinlsChild (hWndChild, hWndParent) 

The WinlsChild function will return TRUE if hWndChild is a descendant of hWndParent 
or is equal to hWndParent (a window can be a child of itself). A window handle can be 
validated with the WinlsWindow API: 

HAB hab; 

BOOL WinlsWindow (hab, hWnd); 

The WinlsWindow function will return FALSE if the window handle is no longer a 
valid window and TRUE if the window handle is valid. 


A Look at the Frame Window 

Most applications will create at least one window that serves as the main window for 
the application. This window is usually a frame window and in most cases serves as the 
central coordinator for the application (see Figure 3.2). To properly manipulate and co¬ 
ordinate the window activity, it’s important to understand the relationship of the frame 
window to all its frame control windows. The window class WC_FRAME is defined by PM. 
Windows created with class WC_FRAME are responsible for sizing, positioning, and 
coordinating all the frame controls. A frame window is created with a call to 
WinCreateStdWindow. The frame control flags tell PM what frame controls to create as 
children of this frame window. 


Figure 3.2. 

A frame window 
and control window 
identifiers. 
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Each of these control windows has a window class predefined by PM except for the 
client window that is defined by your application. The sizing and positioning of these 
controls is handled by the frame window and notification messages are sent to each win¬ 
dow to tell them the specifics. It is possible to alter the behavior, position, and appear¬ 
ance of these controls by processing some of the messages sent to the frame window, but 
we will discuss that later in this chapter. 

In Chapter 2, “OS/2 Application Window Fundamentals,” we showed how to cre¬ 
ate a frame window and its controls with the WinCreateStdWindow call: 


ULONG flFrameFlags 


HWND hWndClient; 


FCF_TITLEBAR 
FCF_MINMAX 
FCF TASKLIST 


FCF_SYSMENU | FCF_SIZEBORDER J 
FCF_SHELLPOSITION | 

FCF_IC0N; 


hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE 3 

&flFrameFlags, "CLIENT", "Test App", 0, NULL, 100, &hWndClient); 

This creates a frame window with the following frame control windows: titlebar, 
system menu, minmax, and client. Alternatively, you can use the WinCreateWindow API 
to create a window of class WC_FRAME. When you do this, you must pass a pointer to a 
FRAMECDATA structure for the class-specific data in the WinCreateWindow call. The 
FRAMECDATA is defined as follows: 


typedef struct _FRAMECDATA { 
USHORT cb; 

ULONG flCreateFlags; 
HMODULE hmodResources; 
USHORT idResources; 

} FRAMECDATA; 


cb 

flCreateFlags 
hmodResources 
idResources 


size of the FRAMECDATA structure 
frame control flags 
module handle for resources 
identifier of resources 


To create a frame window in this way, you first fill in the FRAMECDATA fields and pass 
this information to WinCreateWindow: 


FRAMECDATA FrameData; 

FrameData.cb = sizeof(FRAMECDATA); 

FrameData.flCreateFlags = FCF_TITLEBAR 1 FCF_SYSMENU | FCF_SIZEBORDER 

FCF_MINMAX | FCF_SHELLPOSITION | 
FCFJTASKLIST j FCF_IC0N; 

FrameData.hmodResources = NULL; 

FrameData.idResources = 100; 


hWndFrame = WinCreateWindow (hWndParent, WC_FRAME, "Frame Title", 
0L, 0, 0, 0, 0, NULL, HWND_T0P, 100, 

(PVOID)(PFRAMECDATA)&FrameData, NULL); 
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This creates the frame window and the specified control windows. It does not create 
a client window. With the frame window created, you then create the client window for 
this frame by using the client window’s class and an identifier of FID_CLIENT: 

hWndClient = WinCreateWindow (hWndFrame, "CLIENT", NULL, 

0L, 0, 0, 0, 0, NULL, HWND_BOTTOM, FID_CLIENT, NULL, NULL); 

To prevent unnecessary repainting and resizing during the creation process, the frame 
window is created without the WS_VISIBLE style bit. After the window and all its chil¬ 
dren have been created, call WinShowWindow to make it visible: 

WinShowWindow (hWndFrame, TRUE); 

The window handles of the frame control windows can be queried by using the 
WinWindowFromID API and the predefined frame control IDs: 

HWND hWndTitleBar = WinWindowFromID (hWndFrame, FID_TITLEBAR); 

HWND hWndSysMenu = WinWindowFromID (hWndFrame, FID_SYSMENU); 

HWND hWndMenu = WinWindowFromID (hWndFrame, FID_MENU); 

HWND hWndMinMax = WinWindowFromID (hWndFrame, FID_MINMAX); 

HWND hWndClient = WinWindowFromID (hWndFrame, FID_CLIENT); 

HWND hWndVScroll = WinWindowFromID (hWndFrame, FID_VERTSCROLL); 

HWND hWndHScroll = WinWindowFromID (hWndFrame, FID_H0RZSCR0LL); 

A more practical and efficient way of querying the window handles of a range of 
window IDs is to use the WinMultWindowFromIDs function. This function fills in an array 
with the handles of the child windows that fall within the specified range of identifiers. 
After the call, the individual window handles can be indexed by subtracting the identi¬ 
fier from the base identifier of the range. For example, to retrieve all the frame control 
window handles: 

HWND hWndFrameControls[FID_CLIENT - FID_SYSMENU + 1]; 

LONG ICount; 

ICount = WinMultWindowFromIDs (hWndFrame, hWndFrameControls, 
FID_SYSMENU, FID__CLIENT) ; 

ICount tells how many window handles were found in the range FID_SYSMENU to 
FID_CLIENT. Each entry in the array hWndFrameControls is filled with a window handle 
or NULL if no window with the identifier exists. You can now reference a specific window 
handle by subtracting the identifier from the base identifier of the array (FID_SYSMENU) 
in this case. 

HWND hWndTitleBar = hWndFrameControls[FID_TITLEBAR - FID_SYSMENU]; 

HWND hWndSysMenu = hWndFrameControls[FID_SYSMENU - FID_SYSMENU]; 

HWND hWndMenu = hWndFrameControls[FID_MENU - FID_SYSMENU]; 

HWND hWndMinMax = hWndFrameControls[FID_MINMAX - FID_SYSMENU]; 

HWND hWndClient = hWndFrameControls[FID_CLIENT - FID_SYSMENU]; 

HWND hWndVScroll = hWndFrameControls[FID_VERTSCROLL - FID_SYSMENU]; 
HWND hWndHScroll = hWndFrameControls[FIDJHORZSCROLL - FID_SYSMENU]; 
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WinMultWindowFromIDs can be used with any parent window to query any range of 
child window identifiers. 

Window Characteristics 

Each window is defined by many characteristics including its position, size, parent, owner, 
style, and others. All these characteristics can be queried and changed at any time. 

For a window to be seen on the screen, it must be visible. If a window is not visible, 
none of its children are visible either. When a window is created, one of the flags you can 
use is the WS_VISIBLE flag. This flag is part of the window style and can be changed in 
various ways. For example, when a window is minimized and an icon is defined for the 
window, the frame window is made invisible (hidden); thus, none of its child windows 
are visible. The WinShowWindow or WinSetWindowPos functions can be used to change 
the visibility state of a window. For instance, to hide a window, use this line of code: 

WinShowWindow (hWnd, FALSE) 

or use this line of code: 

WinSetWindowPos (hWnd, 0L, 0L, 0L, 0L, 0L, SWPJHIDE); 

To show a window, use this line of code: 

WinShowWindow (hWnd, TRUE); 
or use this line of code: 

WinSetWindowPos (hWnd, 0L, 0L, 0L, 0L, 0L, SWP_SHOW); 

It is more efficient to use the WinSetWindowPos call because WinShowWindow calls 
WinSetWindowPos with the proper flag. This function sets or clears the WS_VISIBLE flag 
in the window style. It does not enumerate the children and set or clear the WS_VISIBLE 
flag for each one; however, it does keep track of whether the children are currently vis¬ 
ible. The WinlsWindowVisible API can be used to query the current visibility state of a 
window: 

BOOL bVisible = WinlsWindowVisible (hWnd); 

It is important to notice a particular nuance of the visibility state of minimized win¬ 
dows. The visibility state of the frame window of a minimized window is TRUE, whereas 
that of its frame controls and client window is false. Keep this in mind when checking 
the visibility state of the window in which you are interested. 

A window can be enabled or disabled. When a window is enabled, it can receive user 
input, including being selected by the user clicking the window with the mouse. A 
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disabled window cannot receive user input and cannot be clicked with the mouse. The 
purpose of disabling a window is to prevent unwanted input while another activity is 
occurring or to prevent a window from being selected when it doesn’t make sense for 
that particular input to occur. For example, if your application displays a dialog box, the 
owner window is disabled so that only the controls in the dialog box can be selected. 
Clicking the owner window is not allowed. A window can be enabled or disabled with 
the WinEnableWindow API: 

BOOL bEnable = FALSE; 

WinEnableWindow (hWnd, bEnable); 

This will disable the window hWnd and all its child windows. The window can be 
reenabled by calling WinEnableWindow with bEnable set to TRUE. A window can also be 
initially created in the disabled state by using the WS_DISABLED flag for the window style. 
It is usually a good practice to reset the enabled state of a window to its previous state 
when you no longer need the window to be in the disabled state. If the window is already 
disabled when you disable it, you may not want to arbitrarily set it to the enabled state 
when your function completes. The WinlsWindowEnabled API can be used to retrieve 
the current enabled state of a window: 

BOOL bPrevEnabled = WinlsWindowEnabled (hWnd); 

WinEnableWindow(hWnd, FALSE); 

... perform operations ... 

WinEnableWindow (hWnd, bPrevEnabled); 

A maximized window is one that is enlarged to fill the entire area of its parent win¬ 
dow. A window can be maximized in one of three ways. The user can click the maximize 
button of the window; the WS_MAXIMIZED style can be specified when the window is cre¬ 
ated; or WinSetWindowPos can be called with the SWP_MAXIMIZE flag: 

WinSetWindowPos (hWnd, 0L, 0L, 0L, 0L, 0L, SWP_MAXIMIZE); 

A minimized window is one that has been reduced to the size of an icon in its parent 
window. Like maximizing, a window can be minimized in one of three ways. The user 
can click the minimize button of the window; the WS_MINIMIZED style can be specified 
when the window is created; or the WinSetWindowPos can be called with the SWP_MINIMIZE 
flag: 

WinSetWindowPos (hWnd, 0L, 0L, 0L, 0L, 0L, SWP_MINIMIZE); 

A maximized or minimized window can be restored in one of two ways. The user can 
click the restore button of the window, or the SWP_RESTORE flag can be used with the 
WinSetWindowPos call: 
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WinSetWindowPos (hWnd 3 0L, 0L, 0L, 0L 3 0L 5 SWP_RESTORE); 

The current minimized or maximized state can be retrieved in two ways. A call to 
WinQueryWindowPos retrieves the current size and position of the window. In addition, 
WinQueryWindowPos supplies the SWP flags indicating its current state: 

SWP Swp; 

BOOL bMinimized; 

BOOL bMaximized; 

WinQueryWindowPos (hWnd 3 &Swp); 
bMinimized = Swp.fl & SWP_MINIMIZE; 
bMaximized = Swp.fl & SWP_MAXIMIZE; 

A second and easier way is to query the current window. The resulting style can be 
checked with the WS_MINIMIZED and WS_MAXIMIZED flags, WS_MINIMIZED and 
WS_MAXIMIZED. 

ULONG ulStyle; 

ulStyle = WinQueryWindowULong (hWnd, QWL_STYLE); 
bMinimized = ulStyle & WS_MINIMIZED; 
bMaximized = ulStyle & WS_MAXIMIZED; 

Window Data 

When a window is created, a data structure is allocated to contain the information per¬ 
taining to the particular class of window. An application has access to several fields of 
the window data. You have already looked at the window style by using the 
WinQueryWindowULong API and the QWL_STYLE parameter. The size of the data struc¬ 
ture allocated varies depending on the class of the window. An application can define a 
number of bytes to be allocated in addition to the system-defined data structure size, and 
can use these bytes to maintain any application-specific data for the window. The num¬ 
ber of additional bytes to allocate is specified when the window class is registered. In the 
following example, a class called "CLIENT" is registered, specifying that 8 extra bytes should 
be allocated for each window created of this class: 

WinRegisterClass (hab 3 "CLIENT", ClientWndProc, 0L, 8L); 

This application-defined data can be accessed by an offset starting at offset zero. Using 
our example, if you want to store 2 ULONG values with the window, the first ULONG is 
at offset 0 and the second ULONG is at offset 4. It is recommended that you do not hard 
code sizes, but use the sizeof directive to accumulate the sizes of the values you want to 
maintain. 

There are six different APIs available to access or modify the window-extra data. Each 
one requires a window handle and an offset into the data structure. The size and type of 
the value retrieved or set is determined by the API used: 
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WindSetWindowllShort and WinQueryWindowUShort access USHORT values: 

USHORT usValue; 

ULONG ulOffset; 

WinSetWindowllShort (hWnd, ulOffset, usValue); 
usValue = WinQueryWindowUShort (hWnd, ulOffset); 


WinSetWindowULong and WinQueryWindowULong access ULONG values: 


ULONG ulValue; 

ULONG ulOffset; 

WinSetWindowULong (hWnd, ulOffset, ulValue); 
ulValue = WinQueryWindowULong (hWnd, ulOffset); 


WinSetWindowPtr and WinQueryWindowPtr access pointer values: 


PVOID pData; 

ULONG ulOffset; 

WinSetWindowPtr (hWnd, ulOffset, pData); 
pData = WinQueryWindowPtr (hWnd, ulOffset); 

The data within the predefined PM window data structure is accessed with predefined 
identifiers. Notice that whereas application-defined data is referenced with positive value 
offsets, the PM window data is referenced by negative values. These negative values are 
not offsets by any means, but are predefined identifiers that enable PM to know which 
field to return. The prefix of the identifier defines the size of the field. 

QWS_ Value is a short. 

QWL_ Value is a long. 

QWP_ Value is a pointer. 


Identifier 

Value 

Description 

QWS_ID 

(-D 

Window identifier. 

QWL_STYLE 

(-2) 

Window style. 

QWP_PFNWP 

(-3) 

Window procedure. 

QWLJHMQ 

(-4) 

Message queue for window. 


For example, to retrieve the identifier for a window: 

USHORT usID = WinQueryWindowUShort (hWnd, QWS_ID); 
or to retrieve the message queue for a window: 

HMQ hMQ = (HMQ)WinQueryWindowULong (hWnd, QWL_HMQ); 
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Because a frame window is registered as its own class, it also defines some window 
extra data when the WC_FRAME class is registered. The frame-specific data can be set and 
queried just as application-defined data. 


Identifier 

Value 

Description 

QWS_USER 

0 

Start of application 
data. 

QWL_USER 

0 

Start of application 
data. 

QWLJHHEAP 

0x0004 

Handle to heap. 

QWSJFLAGS 

0x0008 

Window flags. 

QWSJRESULT 

0x000a 

Dialog result value. 

QW S_XREST O RE 

0x000c 

X position for restored 
window. 

QWS_YRESTORE 

OxOOOe 

Y position for restored 
window. 

QWS_CXRESTORE 

0x0010 

Width of restored 
window. 

QWS_CYRESTORE 

0x0012 

Height of restored 
window. 

QWS_XMINIMIZE 

0x0014 

X position of mini¬ 
mized window. 

QWS_YMINIMIZE 

0x0016 

Y position of mini¬ 
mized window. 

QWL_HWNDFOCUSSAVE 

0x0018 

Descendant window 
to receive focus when 
this window receives 
the focus. 


Notice that the frame window-specific values are actual offsets into the window extra 
bytes allocated for the frame window. In addition to the documented offsets, here are 
some additional offsets that can be used. However, do not depend on this remaining the 
same in future versions of OS/2, and it is recommended that you do not modify these 
values. 


Identifier 

Value 

Description 

QWL_HACCEL 

0x00lc 

Handle to window 
accelerator table. 

QWL_HICON 

0x0020 

Icon handle for 
window. 

QWL_PWNDICONTEXT 

0x002a 

Handle of icontext 
window. 
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Identifier 

Value 

Description 

QWS_FCAPTURED 

0x0032 

Flag set if window has 
mouse capture. 

QWS_CXSIZEBORDER 

0x0034 

Width of the window’s 
size border. 

QWS_CYSIZEBORDER 

0x0036 

Height of the window’s 
size border. 

QWLJPWNDHELP 

0x0038 

Handle of help window. 

QWS_HMOD 

0x0046 

Module handle of 
window resources. 


Window Sizing and Positioning 

The position of a window is always specified relative to its parent window. The initial 
size and position of a window is specified when the window is created, but can be changed 
at any time by the application. You may have noticed by now that the call to 
WinCreateStdWindow does not have parameters for specifying an initial size or position. 
If the FCF_SHELLPOSITION is specified, PM will calculate a default size and position for 
the window. PM does this internally by calling WinQueryTaskSizePos as shown here: 

SWP Swp; 

Swp.hwndlnsertBehind = HWND_T0P; 

SWP.fl = (SWP_ACTIVATE | SWP_SIZE | SWP_MOVE); 

Swp.x = 20; 

Swp.y = 20; 

Swp.cx = 600; 

Swp.cy =310; 

WinQueryTaskSizePos (hab, 0, &Swp); 

The SWP structure returned describes an initial X and Y position and width and height 
for the first window created by an application. The WinQueryWindowPos function calcu¬ 
lates this information for a frame window having the FCF_STANDARD flag. If the 
FCF_SHELLPOSITION is not specified, the application is responsible for setting the posi¬ 
tion and size of the window after it is created. 

When creating child windows or other top-level frame windows, the 
FCF_SHELLPOSITION is normally not specified. When using the WinCreateWindow API 
to create a window, you have parameters for specifying the window’s initial position and 
size. 

A window’s current size and position can be retrieved with the WinQueryWindowPos 
API: 

SWP Swp; 

WinQueryWindowPos (hWnd, &Swp); 
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This function fills in the SWP structure with the window’s current size, position, and 
current state: 

typedef struct _SWP { 


ULONG 

fl; 

SHORT 

cy; 

SHORT 

cx; 

SHORT 

y; 

SHORT 

x; 

HWND 

hwndlnsertBehind 

HWND 

hwnd; 

ULONG 

ulReservedl; 

ULONG 

ulReserved2; 


} SWP; 

For the WinQueryWindowPos call, these fields take on the following meaning: 

fl - Current window state 

SWP_MINIMIZE Window is currently minimized 

SWP_MAXIMIZE Window is currently maximized 

Otherwise Window is neither minimized or maximized 

cx - Window width 

cy - Window height 

x - Window X position (relative to lower-left corner of parent) 

y - Window Y position (relative to lower-left corner of parent) 

The other fields are used when setting a window’s position. 

It is also possible to query the window’s position and size with the 
WinQueryWindowRect API: 

RECTL Recti; 

WinQueryWindowRect (hWnd, &Rectl); 


This function fills in a RECTL structure with the window’s current size: 

typedef struct _RECTL { 

LONG xLeft; 

LONG yBottom; 

LONG xRight; 

LONG yTop; 

} RECTL; 

For this call, however, the xLeft and yBottom fields will always be zero. The xRight 
and yTop fields define the width and height of the window. Essentially, this function 
returns the window’s position relative to itself. Given that you have the position of any 
window relative to another window, it is always possible to calculate the window’s posi¬ 
tion relative to still another window. This is accomplished with the WinMapWindowPoints 
API: 
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POINTL Ptl; 

Ptl.x = 0L 
Ptl.y = 0L; 

WinMapWindowPoints (hWndFrom, hWndTo, &Ptl, 1L); 

This function takes the points in Ptl (which are specified relative to hWndFrom) and 
converts them to points relative to hWndTo. Using the earlier call to WinQueryWindowRect, 
you can convert the window’s position from (0,0) to coordinates relative to its parent 
window. 

RECTL Recti; 

WinQueryWindowRect (hWnd, &Rectl); 

WinMapWindowPoints (hWnd, WinQueryWindow (hWnd, QW_PARENT), 

(PPOINTL)&Rectl, 2L); 

The window size is now calculated by subtracting xLef t from xRight and yBottom 
from yTop because both the lower-left and upper-right points were converted. 

To convert a window’s position from or to screen coordinates, you can specify 
HWND_DESKTOP for the from- or to-window handle. 

A window’s size and position can be set with the WinSetWindowPos API. If you want 
to move a window to position (10,10), you use: 

WinSetWindowPos (hWnd, 0L, 10L, 10L, 0L, 0L, SWP_M0VE); 

To change the size to 75 pels by 50 pels, you use: 

WinSetWindowPos (hWnd, 0L, 0L, 0L, 75L, 50L, SWP_SIZE); 

It is possible to move and size a window with a single call by combining the SWP flags: 

WinSetWindowPos (hWnd, 0L, 10L, 10L, 75L, 50L, SWP_M0VE j SWP_SIZE); 

If you have more than one window to move or size, it is more efficient to make a 
single call to WinSetMultWindowPos. This reduces the amount of repainting that occurs 
when individual calls to WinSetWindowPos are made. To use WinSetMultWindowPos, it 
is necessary to create an array of SWP structures, one for each window to move or size. 
Using the earlier example, set the position and size of one window to (10, 10) with a 
size of 75 pels by 50 pels. You’ll also position a second window to (100,100): 

SWP Swp[2]; 

Swp[0].fl = SWP_SIZE | SWPJ/IOVE; 

Swp[0].x = 10L; 

Swp[0].y = 10L; 

Swp[0].cx = 75L; 

Swp[0].cy = 50L; 

Swp[0].hwnd = hWndOne; 

Swp [ 1 ] . f 1 = SWPJVIOVE; 

Swp[1].x = 100L; 
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Swp[1].y = 100L; 

Swp[1].hwnd = hWndTwo; 

WinSetMultWindowPos (hab, Swp, 2L); 

When a window’s size or position is changed, PM will usually send the window pro¬ 
cedure for the window a WM_ADJUSTWINDOWPOS message. The mpl parameter contains a 
pointer to a SWP structure that specifies the window’s size and position, which allows the 
window procedure to modify the final size or position of the window. The f 1 field of the 
SWP structure must be examined to determine whether the window is being sized or moved 
or both. If you do not have to process the WM_ADJUSTWINDOWPOS message, you can 
prevent this message from being sent to the window procedure by specifying the 
SWP_NOADJUST flag in the f 1 field. 

After a window’s size has changed, the window procedure for the window is sent a 
WM_SIZE message. This message specifies both the old and new window size: 


WM_SIZE 

SHORT1FROMMP (mpl) 
SH0RT2FR0MMP (mpl) 
SH0RT1FROMMP (mp2) 
SH0RT2FR0MMP (mp2) 


Old width 
Old height 
New width 
New height 


If the window has the CS_MOVENOTIFY class style, the window procedure will also be 
sent a WM_M0VE message whenever the window’s position changes. The new position of 
the window must be queried as described previously. 


Whenever a window is moved, any children of that window are also moved an equiva¬ 
lent distance to maintain their position relative to the parent. Frame windows, however, 
can be forced to maintain their current position whenever their owner window moves. 


The FCF_NOMOVEWITHOWNER flag can be used to tell PM that a particular frame win¬ 
dow should not be moved when its owner moves. In many circumstances, an application 
may be interested in a window’s new size only when the window is minimized or maxi¬ 
mized. This is especially important when writing a Multiple Document Interface (MDI) 
application. Rather than query the system every time a WM_SIZE message is received, you 
can use the WM_M IN MAX FRAME message sent when a frame window is minimized, maxi¬ 
mized, or restored. The mpl parameter contains a pointer to a SWP structure defining the 
action that is about to occur. At the time the WM_M INMAX FRAME message is received, the 
window’s size has not been changed. To have PM perform the default action, do nothing 
to the SWP structure and return FALSE. If you want to perform your own minimizing, 
maximizing, or restoring, return TRUE, and PM will perform no action. It s also possible 
to do a little of both by modifying the SWP structure and returning FALSE. Because the 
SWP structure passed is the same one that PM will use when FALSE is returned, changes 
you make will be used by PM. You will see an example of using the WM_M INMAX FRAME 
message in the example program. 
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Window Focus and Activation 

All keyboard input is sent to the window that currently has the focus. The focus window 
is then responsible for processing the keyboard messages it receives. Focus can be changed 
by calling WinSetFocus. When a window receives or loses the focus, it is sent a 
WM_SETFOCUS message. 

When a window is receiving the focus, the parameters are set to the following: 

mpl - Handle of window losing the focus 
mp2 - TRUE 

When a window is losing the focus, the parameters are set to the following: 

mpl - Handle of window gaining the focus 
mp2 - FALSE 

PM does not allow an application to change the focus while focus is in the process of 
changing. Calls to WinSetFocus during the WM_SETFOCUS message will fail. 

Actually, the call to WinSetFocus results in a call to WinFocusChange with the 
flFocusChange flags set to zero. The WinFocusChange function can be used to change 
the focus without having it generate certain messages. For example, to prevent the 
WM_SETFOCUS message from being sent to the window losing the focus or to the window 
gaining the focus, use the following call: 

WinFocusChange (HWND_DESKTOP, hWndNewFocus, 

FC_NOSETFOCUS | FC_N0L0SEF0CUS); 

The WinQueryFocus function can be used at any time to query the window that 
currently has the focus: 

HWND hWndFocus = WinQueryFocus (HWND_DESKTOP); 

It is not possible to set the focus to a disabled window. Disabling a window that 
currently has the focus causes that window to lose the focus. 

All frame windows that are ancestors of the window with the focus are considered to 
be active windows. An active frame window is usually identified by a border and/or titlebar 
drawn in a highlighted state. When a frame window becomes active, the client window 
receives a WM_ACTIVATE message. If a frame window is becoming active, the mpl param¬ 
eter is TRUE, and mp2 is the handle of the frame window becoming active. If a frame win¬ 
dow is losing activation, the mpl parameter is FALSE, and mp2 is the handle of the frame 
window losing activation. 

Application Activation 

A window receives a WM_ACTIVATE message when it is activated or deactivated. The first 
parameter of the message is TRUE if gaining activation, and FALSE if losing activation. If 
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a window is active, all its ancestors are active. When a frame window receives the 
WM_ACTIVATE message, it responds by setting or clearing the FF_ACTIVE bit of the frame 
flags (QWS_FLAGS), sending the TBM_SETHILITE message to the FID_TITLEBAR window, 
and redrawing the frame in either the highlighted or unhighlighted state. The frame 
window then passes this message to the client window. 

This message, however, gives no indication whether the application is gaining activa¬ 
tion or losing activation. This would be useful if certain events should be active only while 
the application is the active application. For example, an application that is a clipboard 
viewer should set itself as the clipboard viewer only when the application is active and 
then release itself as the viewer when not active. Because the window activation can change 
to another window in the same application (a message box being displayed), looking for 
the WM_ACTIVATE message does not sufficiently show the activation state of the applica¬ 
tion. You would need to know the identity of the other window receiving or losing acti¬ 
vation to know whether that window is in another application. 

One way to attempt this is to set or clear a global flag whenever one of the windows 
receives the WM_ACTIVATE message. If the flag was not set when you received a TRUE 
WM_ACTIVATE message, the application is gaining activation from another application. If 
the flag was set when you received a FALSE WM_ACTIVATE message, the application is los¬ 
ing activation to another application. The problem with this is that if the activation is 
changing to another window within the same application, the final state of the flag would 
be FALSE. This is because the TRUE WM_ACTIVATE message is sent before the FALSE 
WM_ACTIVATE message. The flag would be set to FALSE by the second WM_ACTIVATE 
message. 

You can take advantage of another message used when focus is changing from one 
window to another. The WM_FOCUSCHANGE message is sent whenever the focus is chang¬ 
ing from one window to another. It is a notification message that is passed up the owner 
chain telling each side of the focus process who is losing the focus and who is gaining 
the focus. If Window A is gaining the focus and Window B is losing the focus, a 
WM_FOCUSCHANGE message is sent to both Window A and Window B. 

Window Message nip 1 SHORTlFROMMP(mp2) 

Window A WM_FOCUSCHANGE Window B TRUE 
Window B WM_FOCUSCHANGE Window A FALSE 

Notice that each window receives the identity of the window on the other side of the 
focus change. If you check the message queue handles of each window and they are the 
same, focus is changing to another window in the same application. If the message queues 
are different, focus and activation are changing between applications. Because the 
WM_FOCUSCHANGE message is passed along the owner chain, you can check this message 
in the window procedure for the top-level window of the application. 
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case WM_FOCUSCHANGE: 

if ( WinQueryWindowULong (hWnd, QWL_HMQ) != 

WinQueryWindowULong ((HWND)mpl, QWLJHMQ) ) 

{ 

if (SH0RT1FROMMP(mp2)) 

/* Application is gaining activation */ 
bAppIsActive = TRUE; 

else 

/* Application is losing activation */ 
bAppIsActive = FALSE; 

} 

mReturn = WinDefWindowProc (hWnd, ulMsg, mpl, mp2); 

break; 

When the WM_FOCUSCHANGE is received, you check the message queue handles. If they 
are the same, there is nothing to do. If they are different, you are changing application 
activation. If SH0RT1 FROMMP (mp2) is TRUE, the application is gaining activation; other¬ 
wise, the application is losing activation. Passing the WM_FOCUSCHANGE message to 
WinDefWindowProc simply causes the message to be passed to the frame window’s owner 
window. 


Window Subclassing 

When a class is registered, a window procedure is specified. This window procedure re¬ 
ceives and processes all messages associated with windows of that class. When a window 
is created, a block of memory is allocated to maintain information for the window. The 
window’s current position, owner window, parent window, and current style are examples 
of this type of information (see Figure 3.3) . In addition, the window procedure for the 
class is copied to this block of memory and is called when a message is to be processed for 
the window. 

When you want to alter the behavior of a window, you can subclass the window so 
that a different window procedure is called. Subclassing is performed only on the speci¬ 
fied window. To subclass a window, use the WinSubclassWindow function specifying a 
new window procedure. 

PFNWP OldWndProc; 

OldWndProc = WinSubclassWindow (hWnd, MyNewWndProc); 

The return value from WinSubclassWindow is the previous window procedure. It is 
important to save this value and pass messages that your new window procedure does 
not process to the previous window procedure. When you are done subclassing the win¬ 
dow, the window procedure can be reset by calling WinSubclassWindow again: 

WinSubclassWindow (hWnd, OldWndProc); 
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Figure 3.3. 

PM window structure 
information. 


Window Handle 


PM Window Structure Information 



All the predefined PM window classes use window procedures defined in PM. Your 
application, thus, never receives or processes messages for the frame or its controls unless 
the frame passes the message to the client window. By subclassing the frame or its con¬ 
trols, you can change the default behavior of these windows. In the following sections, 
you will look at various things that can be done by subclassing the frame window or the 
frame controls. We will do this principally by subclassing the frame window: 

PFNWP pfnFrameProc; 

pfnFrameProc = WinSubclassWindow (hWndFrame, FrameSubclassProc); 

When OS/2 sends a message to a subclassed window procedure, the subclassed win¬ 
dow procedure may or may not process the message. For messages you are not interested 
in or for those cases where you process the message, but still want PM to do something, 
call the default window procedure for the frame window: 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
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Titlebar Painting 

During the normal course of operation, your application has control only of how the 
client window is painted; however, it is possible to do your own painting of the frame 
window and its controls by intercepting the WM_PAINT messages. As an example, suppose 
you are writing a game program and want to use the titlebar area to display a bitmap 
showing the number of children that exist. You start by creating the frame window with¬ 
out the WS_VISIBLE flag. This enables you to subclass the titlebar before its first paint 
message. Next, subclass the titlebar window: 

MRESULT EXPENTRY TitleBarSubclassProc (HWND,ULONG,MPARAM,MPARAM); 

PFNWP pfnTitleBarProc; 


hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0L, 

&flFrameFlags, szClientClass, szTitle, 0, NULL, 

ID_APPNAME, &hWndClient); 

pfnTitleBarProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_TITLEBAR), TitleBarSubclassProc); 

WinShowWindow (hWndFrame, TRUE); 

In this example, you will draw a heart-shaped image in the titlebar window. You will 
do something a little differently here. You will use a pointer rather than a bitmap because 
the color of the titlebar can be controlled by the desktop settings. Because you don’t know 
in advance what that color will be, you must draw the image in the window and leave the 
background color alone wherever the images background bits appear. This can be done 
through several steps by using various ROP (raster operation) codes and the GpiBitBlt 
API, but there is an undocumented API that enables you to take advantage of the fact 
pointers and icons are drawn in exactly this manner (that is, transparent bit bit). The 
function, Win32StretchPointer, is identical to the WinDrawPointer API except that it 
enables you to specify the target width and height for the pointer. This function will stretch 
or shrink the pointer to fit the target, but leave the background bits alone. This function 
will work only for pointers and icons, so the source image can be no larger than 32x32. 

You load the pointer during the WM_CREATE message for the client window and de¬ 
stroy it during the WM_DESTROY message: 

extern BOOL APIENTRY Win32StretchPointer(HPS hps, SHORT x, SHORT y, 

SHORT cx, SHORT cy, HPOINTER hptr, USHORT fs); 

HPOINTER hPtrHeart = NULL; 

ULONG NumChildren = 0L; 

MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 


{ 
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BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

HPS hps; 

switch (msg) 

{ 

case WM_CREATE: 

hPtrHeart = WinLoadPointer (HWNDJDESKTOP,0L,IDPTRJHEART); 
break; 

case WM_DESTROY: 

WinDestroyPointer (hPtrHeart); 
break; 


} 

return (mReturn); 


Next, we define the window procedure for the titlebar window subclass. For the 
titlebar, you must process three different messages. The titlebar window maintains an 
internal state value indicating its current highlighted state. Because you don’t have direct 
access to that field, you can use the fact that the WC_TITLEBAR class is defined with win¬ 
dow extra words, including a long for the QWL_USER field. You can use this field to keep 
track of the current state. You will set the low bit to 1 if the titlebar window is currently 
in the highlighted state: 

#define ISJHIGHLIGHTED 0x0001L 

MRESULT EXPENTRY TitleBarSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

MRESULT mReturn = 0L; 

ULONG ulCurState, 
ulNewState; 

HPS hps; 

switch (msg) 

{ 

case WM_MOUSEMOVE: 

WinSetPointer (HWND_DESKTOP, hPtrTitleBar); 
break; 

case TBM_QUERYHILITE: 

mReturn =(MRESULT)(WinQueryWindowULong(hWnd,QWLJJSER) 

& ISJHIGHLIGHTED); 

break; 


case TBM SETHILITE: 



Chapter Cj Window Management 


mReturn = (MRESULT)TRUE; 

ulCurState = ulNewState = WinQueryWindowULong (hWnd,QWL_USER); 
if (LOUSHORT(mp1)) 

ulNewState |= IS_HIGHLIGHTED; 
else 

ulNewState &= ~IS_HIGHLIGHTED; 

/* Only need to update if the state is changing */ 
if (ulCurState == ulNewState) 
break; 

WinSetWindowULong (hWnd,QWL_USER,ulNewState); 

hps = WinGetPS (hWnd); 

PaintTitleBar (hWnd,hps); 

WinReleasePS (hps); 
break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

PaintTitleBar (hWnd,hps); 

WinEndPaint (hps); 
break; 

default: 

mReturn = (*pfnTitleBarProc) (hWnd, msg, mpl, mp2); 
break; 


return (mReturn); 

} 


The TBM_QUERYHILITE message requests the current highlighted state of the titlebar. 
The TBM_SETHI LITE message says to set the current highlighted state to that in 
LO JSHORT (mpl ). You query the current state and compare it with the new state. If there 
is no change, there is nothing to do. Otherwise, set the new state and repaint the titlebar 
window in its new state. When you get the WM_PAINT message, you merely repaint the 
titlebar window. For all other messages, you pass the message on to the default titlebar 
window procedure. 

For the painting of the titlebar window, you define the function PaintTitleBar: 

#define DB_RAISED 0x0400 

#define DB_CORNERBORDER 0x8000 
#define IS_HIGHLIGHTED 0X0001L 

V0::d PaintTitleBar (HWND hWnd, HPS hps) 

{ 

RECTL Recti; 

BOOL bActive; 
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SHORT Scale, 

X; 

ULONG inx; 

/* If window is not visible then nothing to paint */ 
if (IWinlsWindowVisible (hWnd)) 
return; 

/* Get the current active state of the titlebar */ 
bActive = (BOOL)(WinQueryWindowULong (hWnd, QWLJJSER) 

& IS_HIGHLIGHTED); 

/* Draw the correct border for the titlebar */ 

WinQueryWindowRect (hWnd, &Rectl); 

WinDrawBorder (hps, &Rectl, bActive ? 0L : 1L, 1L, 

SYSCLR_TITLEBOTTOM, 

bActive ? SYSCLR_ACTIVETITLE : SYSCLR_INACTIVETITLE, 

DB_RAISED | DB_CORNERBORDER | DB_STANDARD | DB_INTERIOR); 

/* Draw a heart for each child window that exists. Scale the pointer 
to fit in the titlebar height minus 2 minus the nominal border 
width times 2. Since the WC_TITLEBAR class is not CS_CLIPSIBLINGS 
it is possible to write over the minmax window. Only output as 
many hearts as will fit in the titlebar window. Use the 
Win32StretchPointer API so we get a transparent bitbit.*/ 

Scale = (SHORT)(Recti.yTop - Recti.yBottom - 2 - 

2 * WinQuerySysValue (HWND_DESKTOP, SV_CYBORDER)); 

if (bAppIsActive) 

{ 

if ((inx = ulNumChildren) != 0) 

{ 

X = (SHORT)(WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) +1); 
while ( inx && ((LONG)(X + Scale) < Recti.xRight) ) 

{ 

Win32StretchPointer (hps, X, 2, Scale, Scale, hPtrHeart, 
DP_NORMAL); 
inx - -; 

X += (SHORT)(Scale + 2); 

} 

} 

else 

{ 

POINTL Ptl; 

Ptl.x = WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) + 1; 

Ptl.y = 2; 

GpiCharStringAt (hps, &Ptl, 21L, (PSZ)"MiniMDI - No children"); 


} 



Chapter 3 Window Management 


else 

{ 

POINTL Ptl; 

Ptl.x = WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) + 1; 

Ptl.y = 2; 

GpiCharStringAt (hps, &Ptl, 20L, (PSZ) "MiniMDI - Not Active 11 ); 


return; 


If the window is not visible, there is nothing to paint. Otherwise, query the current 
state and use the WinDrawBorder function to draw the border around the window and 
fill its interior. Finally, you draw a heart in the window for each child. Because the 
WC_TITLEBAR class does not include the CS_CLIPSIBLINGS flag, it is possible to draw 
outside the titlebar window and over sibling windows. For that reason, you do not want 
to draw a heart that might extend past the end of the titlebar window rectangle. Because 
the titlebar is drawn with a raised border, subtract the height of the border and then sub¬ 
tract 2 to provide a separation between the border and the heart. 

Mouse Pointer 

The mouse pointer displays the current position of the mouse. The pointer that is used 
is set by the application whenever a WM_M0USEM0VE message is received or when time- 
consuming processing is about to begin. Typically, the mouse pointer is set to display a 
pointer that represents the type of operation performed in a window. The default pointer 
used, if no setting of the pointer is done by the application, is the arrow pointer. 

To control the pointer in your client window, set the pointer when the application 
receives the WM_MOUSEMOVE message: 

case WMJVIOUSEMOVE: 

WinSetPointer (HWND_DESKTOP 3 hPtrNew); 
break; 

When the mouse is positioned over a control window, the control will send a 
WM_ CONTROLPOINTER message to its owner: 

WM_CONTROLPOINTER 

SH0RT1FROMMP(mpl) = identifier of control window 
mp2 = handle of pointer to use 

The return value for this message is the handle of the pointer to display. Passing this 
message to WinDefWindowProc will return the handle contained in mp2. The owner can 
change the pointer by returning a different pointer handle. This example sets a different 
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pointer if the pointer is over the window with identifier ID_TOOLBAR: 

case WM_CONTROLPOINTER: 

if (SH0RT1FROMMP(mpl) == ID_T00LBAR) 
mReturn = hPtrHeart; 

else 

mReturn = mp2; 
break; 

It is possible to set the pointer for the frame window and its controls by subclassing 
the frame window. The frame window will receive the WM_CONTROLPOINTER for the sys¬ 
tem menu, actionbar menu, minmax menu, and the frame. No WM_CONTROLPOINTER 
message will be received from the titlebar window because it does not send one to its 
owner. The titlebar merely sets it to the arrow pointer; however, if you subclass the tidebar, 
you can set the pointer by processing the WM_MOUSEMOVE message. In the sample applica¬ 
tion, you will set the pointer to represent the frame control that the mouse is over. In 
addition, you will use a feature of the mouse WM_HITTEST result to indicate exactly what 
part of the frame window the mouse is over. 

You begin by subclassing the frame window, titlebar window, system menu, and 
actionbar menu: 

pfnFrameProc = WinSubclassWindow (hWndFrame,FrameSubclassProc); 
pfnTitleBarProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_TITLEBAR), TitleBarSubclassProc); 
pfnSysMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_SYSMENU), SysMenuSubclassProc); 
pfnMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_MENU), MenuSubclassProc); 

While the WM_CONTROLPOINTER for the system menu and actionbar menu is passed 
to the frame window, you have no way of knowing if the mouse is over a pull-down menu. 
By subclassing these two windows, you know that the WM_CONTROLPOINTER received is 
for a pull-down or cascaded menu owned by the top-level menu. You don t subclass the 
minmax menu because it does not have a pull-down menu. In FrameSubclassProc, you 
will process both the WM_CONTROLPOINTER and WM_MOUSEMOVE messages: 

MRESULT EXPENTRY FrameSubclassProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn; 

HPOINTER hPtr; 

switch (msg) 

{ 

case WM_CONTROLPOINTER: 

switch (SHORT1FROMMP(mpl)) 

{ 
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case FID_SYSMENU: 

mReturn = hPtrSysMenu; 
break; 

case FID_MENU: 

mReturn = hPtrMenu; 
break; 

case FID_MINMAX: 

mReturn = hPtrMinMax; 
break; 
default: 

mReturn = mp2; /* Use the default pointer */ 

} 

break; 

case WM_MOUSEMOVE: 

switch (SHORT1FR0MMP(mp2)) 

{ 

case TF_LEFT: 
case TF_RIGHT: 

hPtr = hPtrLeft; 
break; 

case TF_TOP: 
case TF_BOTTOM: 
hPtr = hPtrTop; 
break; 

case TF_LEFT | TF_T0P: 
case TF_RIGHT | TF_BOTTOM: 
hPtr = hPtrLeftTop; 
break; 

case TF_RIGHT | TF__TOP: 
case TF_LEFT | TF_B0TT0M: 
hPtr = hPtrRightTop; 
break; 
default: 
hPtr = 0; 

} 

if (hPtr) 

WinSetPointer (HWND_DESKTOP, hPtr); 

else 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
break; 

default: 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
break; 


return (mReturn); 

} 
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The WM_MOUSEMOVE message for the frame window contains the WM_HITTEST code in 
SH0RT1FROMMP (mp2). This value will tell you what part of the frame window the cursor 
is over. The flags used for the WM_TRACKFRAME message are used for all the sides of the 
frame window, so you can key off these values to determine which pointer to display. If 
it is not one of these flags, either the mouse is being captured, there is no sizeborder con¬ 
trol for the frame, or the window is minimized. 

In TitleBarSubclassProc, you will process the WM_M0USEM0VE message: 

MRESULT EXPENTRY TitleBarSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

MRESULT mReturn; 


switch (msg) 

{ 

case WM_M0USEM0VE: 

WinSetPointer (HWND_DESKTOP, hPtrTitleBar); 
break; 

default: 

mReturn = (*pfnTitleBarProc) (hWnd, msg, mpl, mp2); 
break; 

} 

return (mReturn); 

} 

In SysMenuSubclassProc and MenuSubclassProc, you process the 
WM_C0NTR0LP0INTER message: 

MRESULT EXPENTRY SysMenuSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

if (msg == WM_CONTROLPOINTER) 
return (hPtrPopupMenu); 

else 

return (*pfnSysMenuProc) (hWnd, msg, mpl, mp2); 

} 

MRESULT EXPENTRY MenuSubclassProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

if (msg == WM_C0NTR0LP0INTER) 
return (hPtrPopupMenu); 

else 


} 


return (*pfnMenuProc) (hWnd, msg, mpl, mp2); 
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For the client window, you will set the pointer when the WM_M0USEM0VE message is 
received: 


case WM_M0USEM0VE: 

WinSetPointer (HWND_DESKTOP, hPtrClient); 
break; 


All the pointers are loaded during the WM_CREATE message and destroyed during the 
WM_DESTROY message in ClientWndProc: 


case WM_CREATE: 
hPtrHeart 
hPtrClient 
hPtrSysMenu 
hPtrMenu 
hPtrMinMax 
hPtrLeft 
hPtrTop 
hPtrLeftTop 
hPtrRightTop 
IDPTR_RIGHTTOP); 

hPtrTitleBar 
IDPTR_TITLEBAR); 

hPtrPopupMenu 
IDPTR_POPUPMENU); 
break; 


= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWNDJDESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 
= WinLoadPointer (HWND_DESKTOP, 


0L 3 IDPTR_HEART); 
0L 3 IDPTR_CLIENT); 
0L 3 IDPTR_SYSMENU) 
0L 3 IDPTR_MENU); 

0L 3 IDPTR_MINMAX); 
0L 3 IDPTR_LEFT); 

0L 3 IDPTR_TOP); 

0L 3 IDPTR_LEFTTOP) 
0L 3 


= WinLoadPointer (HWND_DESKTOP 3 0L 3 


= WinLoadPointer (HWND_DESKTOP 3 0L 3 


case WM_DESTROY: 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

WinDestroyPointer 

break; 


(hPtrHeart); 
(hPtrClient); 
(hPtrSysMenu); 
(hPtrMenu); 
(hPtrMinMax); 
(hPtrLeft); 
(hPtrTop); 
(hPtrLeftTop); 
(hPtrRightTop); 
(hPtrTitleBar); 
(hPtrPopupMenu); 


Figure 3.4 displays the image of each of these declared PTR values. 
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Figure 3.4. 
Image of each 
sample PTR. 



Preventing Window Tracking 

The size of a window can be changed with the mouse by pressing and holding the mouse 
button while positioned on the border of the frame. In addition, a window can be moved 
with the mouse by pressing and holding the mouse button while positioned on the titlebar 
window. This process is referred to as “tracking” the window. When this process starts, 
the frame window receives a WM_TRACKFRAME message. 

WM_TRACKFRAME 

SH0RT1FROMMP(mpl) = Frame tracking flags 

The frame tracking flags can be a combination of the following: 

TFJLEFT 0x0001 

TF_TOP 0x0002 

TF_RIGHT 0x0004 
TFJBOTTOM 0x0008 
TF_MOVE OxOOOF 

The frame tracking flags indicate the operation that is about to start. To prevent a 
particular tracking operation from occurring, intercept the WM_TRACKFRAME message and 
do not pass it to the frame’s window procedure. It is necessary to subclass the frame win¬ 
dow to intercept this message. To prevent the window from being moved, you do the 
following: 
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MF1ESULT EXPENTRY FrameSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mp2) 


{ 


MRESULT mReturn; 


MPARAM mpl , 


switch (msg) 

{ 


case WM_TRACKFRAME: 

if ((SHORT1FROMMP(mpl) & TF_M0VE) == TF_MOVE) 
mReturn = 0L; 

else 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
break; 


} 

return (mReturn); 


To prevent the window from being sized to the right or moved by the mouse, you 
check for the following: 

case WM__TRACKFRAME: 

switch (SHORT1FROMMP(mpl) &TFJ/I0VE) 

{ 

case TFJV10VE: 
case TF_RIGHT: 
case TF_RIGHT | TF_B0TT0M: 
case TF_RIGHT I TF_TOP: 
mReturn = 0L; 
break; 
default: 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 

} 

break; 

Restricting a Window’s Size 

When the frame window receives the WM_TRACKFRAME message, the frame window im¬ 
mediately sends a WM_QUERYTRACKINFO message to itself. The frame window fills in the 
TRACKINFO structure with the data that specifies the minimum and maximum size of the 
tracking rectangle: 

WM_QUERYTRACKINFO 

SH0RT1 FROMMP (mpl) = Tracking flags 

mp2 = Pointer to TRACKINFO structure 
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To restrict the size of a window being resized by the mouse, intercept the 
WM_QUERYTRACKINFO message and set the ptlMinTrackSize and ptlMaxTrackSize fields 
of the TRACKINFO structure. To restrict the movement of the window within a particular 
area, set the rclBoundary field. It is necessary to subclass the frame window to intercept 
this message. 

In the sample application, you use the WM_QUERYTRACKINFO to restrict the minimum 
size to 75 pels by 50 pels. Also, you restrict the maximum size to be 40 pels wider and 
higher than the current width and height. Although you do not restrict the boundary in 
which the window can be moved, you could do that by specifying a rectangle in coordi¬ 
nates relative to the parent window in the rclBoundary field. 

The child window is subclassed when the “Move” or “Track” check boxes are checked: 

WinSubclassWindow (WinQueryWindow (hWndActiveChild, QW_PARENT), 
ChildSubclassProc); 

Because you subclassed another frame window earlier in the application, we have the 
address to PM’s frame window procedure in pf nFrameProc. 

When the WM_QUERYTRACKINFO message is received by ChildSubclassProc, you first 
pass the message to the default frame window procedure. This allows the TRACKINFO 
structure to be initialized by PM. Afterwards, you can update the structure with our 
restrictions on the window sizing and positioning: 

MRESULT EXPENTRY ChildSubclassProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = FALSE; 

MRESULT mReturn = 0L; 

switch (msg) 

{ 

case WM_QUERYTRACKINFO: 
if (WinQueryWindowULong ( 

WinWindowFromID (hWnd, FID_CLIENT), QWL_TRACKING)) 

{ 

PTRACKINFO pti; 

RECTL Recti; 

/* Let the PM frame window function initialize TRACKINFO */ 
mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 

WinQueryWindowRect (hWnd, &Rectl); 
pti = (PTRACKINFO)mp2; 

pti->ptlMinTrackSize.x = 75L; 
pti->ptlMinTrackSize.y = 50L; 
pti->ptlMaxTrackSize.x = Recti.xRight + 40; 
pti->ptlMaxTrackSize.y = Recti.yTop + 40; 
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bHandled = TRUE; 

} 

} 

if (!bHandled) 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
return (mReturn); 

All coordinates specified are relative to the parent window. 


Window Icons 

The icon that is used when a window is minimized is stored with the window informa¬ 
tion for each frame window. This icon can be defined when the window is created, or the 
icon can be set later with the WM_SETICON message. To define an icon when the window 
is created, use the FCF_IC0N frame control flag. The identifier of the icon that will be 
loaded is the same as the identifier of the frame window. The icon resource is loaded 
from the module specified by the module handle field of the WinCreateStdWindow call. 
This example creates a frame window with an icon having identifier ID_APPNAME. 

Here is the resource file: 

ICON ID_APPNAME HEART.ICO 
Here is the header file: 

#define ID_APPNAME 1 
Here is the source file: 

HMQ hmq; 

ULONG flFrameFlags = FCF_TITLEBAR 

FCF_MINMAX 

FCF_IC0N; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (NULL); 
hmq = WinCreateMsgQueue (hab, NULL); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, NULL, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0L, 

&flFrameFlags, szClientClass, szTitle, 0, NULL, ID_APPNAME, 
&hWndClient); 


| FCF_SYSMENU | FCF_SIZEBORDER | 

| FCF_SHELLPOSITION | FCF_TASKLIST 
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You might think the icon with identifier ID_APPNAME is automatically used in this 
example. There is, however, one slight variation that PM adds to this scenario. If the 
identifier of the icon is “1,” PM will attempt to look for an icon-extended attribute. 
If PM finds one, it will use that icon regardless of the icon specified in the 
WinCreateStdWindow call. Here is an outline of the logic used to determine which icon 
is set for a frame window during the creation of the frame window: 

hlcon = NULL; 

if the FCF_IC0N flag is specified 

{ 

if the resource identifier is equal to 1 

hlcon = Search for icon extended attribute using 
the module handle 

if (Ihlcon) 

{ 

hlcon = WinLoadPointer (HWND_DESKTOP, module handle, resource 

id); 

if (lhlcon) 

return (FALSE); 

} 

WinSendMsg(hWndFrame, WM_SETICON, hlcon, 0L); 

} 

If you specify the FCF_ICON flag, but forget to include the icon in the resource file, 
the window creation will fail. The icon used for a frame can be changed at any time by 
sending the WM_SETICON message to the frame window: 

HPOINTER hlcon = WinLoadPointer (HWND_DESKTOP, 0L, 100); 

WinSendMsg (hWndFrame, WM_SETICON, hlcon, 0L); 

The current icon handle can be retrieved by using the WM_QUERYICON message: 

HPOINTER hlcon = WinSendMsg (hWndFrame, WM_QUERYICON, 0L, 0L); 

If there is no icon defined for a frame window, when the window is minimized, no 
icon is displayed and the application is sent a WM_PAINT message to draw in the mini¬ 
mized window area. 

Message Processing 

As discussed in Chapter 2, messages are the primary means of communicating between 
windows and are at the heart of any windowing system. Messages are communicated to 
an application window in two manners: sent or posted. Messages that are sent are di¬ 
rected immediately to the window procedure for a window. If the window that is to 
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receive the message belongs to another process, OS/2 performs the necessary steps to switch 
tasks and returns to the sending task when the message has been processed. Examples of 
sent messages are notification messages such as WM_C0NTR0L, and WM_ACTIVATE. Mes¬ 
sages are sent by using WinSendMsg: 

MRESULT APIENTRY WinSendMsg (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2); 

When WinSendMsg is used, the call does not return until the message is processed 
(see Figure 3.5). 


Figure 3.5. 
Diagram of 
WinSendMsg 
message flow. 


Synchronous 


Process 1 Process 2 



Posted messages are those placed in the message queue of the process that created the 
window and are processed when the receiving application retrieves the message from its 
message queue. Examples of posted messages are WM_SIZE and WM_MOVE. Messages are 
posted by using WinPostMsg: 

MRESULT APIENTRY WinPostMsg (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2); 

When WinPostMsg is used, the call returns immediately after placing the message in 
the appropriate message queue (see Figure 3.6). 
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Figure 3.6. 


Asynchronous 


Diagram of 




WinPostMsg 




message flow. 

Message queue 


Message queue 



It is also possible to post a message to a particular message queue. Messages posted to 
a message queue do not contain a window handle. Applications processing these types of 
messages must explicitly look for a message with no window handle, as these messages 
are not dispatched to any window procedure. Messages are posted to a message queue by 
using WinPostQueueMsg: 

BOOL APIENTRY WinPostQueueMsg (HMQ hmq, ULONG msg, MPARAM mpl, 

MPARAM mp2); 

When you want to send or post a message to all child windows of a particular win¬ 
dow, you can use the WinBroadcastMsg function. This function will either post or send 
a message to all immediate child windows. Broadcasting messages is typically used to notify 
all children that a system-wide or application-wide attribute has changed (see Figure 3.7): 

BOOL APIENTRY WinBroadcastMsg (HWND hWnd, ULONG msg, MPARAM mpl, MPARAM 
mp2, ULONG rgf); 

The rgf parameter can contain the following mutually exclusive flags: 

BMSG_POST Message is posted to the windows. 

BMSG_SEND Message is sent to the windows. 

BMSG_POSTQUEUE Message is posted to the message 

queue of all threads. 
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BMSGJDESCENDANTS 

BMSGJFRAMEONLY 


Broadcast message to all descendants of 
hWnd. 

Only frame windows receive the message. 


Figure 3.7. 

Diagram of 
WinBroadcastMsg 
message flow. 


Broadcast Post 



Broadcast Sent 


Message queue 
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Applications retrieve messages from their message queue by calling either WinGetMsg 
or WinPeekMsg. After a message has been removed from a message queue, it is dispatched 
to the window’s window procedure by calling WinDispatchMsg. There are a couple of 
subtle differences between WinGetMsg and WinPeekMsg. First, look at their definitions: 

BOOL APIENTRY WinGetMsg (HAB hab, PQMSG pqmsg, HWND hwndFilter, 

ULONG msgFilterFirst, ULONG msgFilterLast); 

BOOL APIENTRY WinPeekMsg (HAB hab, PQMSG pqmsg, HWND hwndFilter, 

ULONG msgFilterFirst, ULONG msgFilterLast, ULONG fl); 

Both of these functions are passed a pointer to a QMSG structure. The hWndFilter, 
msgFilterFirst, and msgFilterLast parameters are used for message filtering that you 
will look at in a minute. The main difference is the f 1 parameter for WinPeekMsg. Calls 
to WinGetMsg do not return until a message is placed in the message queue. When a mes¬ 
sage is placed in the queue, WinGetMsg returns after removing the message from the message 
queue (see Figure 3.8). 


Figure 3.8. 
Message flow for 

WinGetMsg. 


Message queue 


empty 


Message queue 


WM COMMAND 


Message queue 


empty 


Process 


Process 



Message 


WinGetMsg 

_Posted - p. 

WinGetMsg 

(waiting) 

to 



Queue 

(WM_COMMAND 



removed 



from queue 



and 



processed) 


WinPeekMsg, however, always returns immediately with its return value that indi¬ 
cates whether a message was found in the queue. WinPeekMsg is typically used to look 
into the queue and see whether messages are waiting to be processed so that processing 
can continue if no messages need to be processed. The f 1 parameter specifies what to do 
with the message if one is found in the queue. 

PM_REMOVE Remove the message from the queue. 

PM_NOREMOVE Do not remove the message from the 

queue. 
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Figure 3.9 shows that a call to WinPeekMsg returns immediately with a return value 
of FALSE when no messages are present in the message queue. 

Figure 3.9. 

Message flow for 

WinPeekMsg. 


Message queue 


empty 


Process 


WinPeekMsg 

(returns 

FALSE 

and 

processing 

continues) 


One important difference between WinGetMsg and WinPeekMsg is the handling of 
the WM_QUIT message. WinGetMsg always returns TRUE unless the message removed from 
the queue is the WM_QUIT message, in which case WinGetMsg returns FALSE. WinPeekMsg 
returns TRUE if a message—even if it is the WM_QUIT message—is in the queue. 

After a message has been removed from the queue, WinDispatchMsg is called to send 
it to the window procedure: 

MRESULT APIENTRY WinDispatchMsg (HAB hab, PQMSG pqmsg); 

The process of dispatching a message is shown in Figure 3.10. A message is removed 
from the queue by calling WinGetMsg. WinDispatchMsg is called to send the message to 
the window procedure for the window to which the message belongs. 
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Figure 3.10. 

WinDispatchMsg 

processing. 



The code for a normal message loop for an application looks something like this: 
QMSG qmsg; 

while (WinGetMsg (hab, &qmsg, 0L, 0L, 0L)) 

WinDispatchMsg (hab, &qmsg); 

You can also implement the exact same loop by using Win PeekMsg and the WinWaitMsg 
functions. 

QMSG qmsg; 

while (WinWaitMsg (hab, 0L, 0L)) 

{ 

while ( WinPeekMsg (hab, &qmsg, 0L, 0L, 0L, PM_REMOVE) && 

(qmsg.msg != WM_QUIT) ) 

WinDispatchMsg (hab, &qmsg); 

if (qmsg.msg == WM_QUIT) 
break; 

} 

The WinWaitMsg function does not return until a message is placed in the message 
queue. WinGetMsg can be used to wait for a particular message if your application is waiting 


m 
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for a particular event to occur. One of the more common uses of the WinPeekMsg call is 
to continue to process messages while a long process is occurring. For example, if a long 
drawing sequence is being performed, you do not want to halt the processing of messages 
in the system while the drawing is being performed. WinPeekMsg, thus, is used to process 
all the messages in the queue, and the drawing is performed only when no messages are 
in the queue. 

QMSG qmsg; 

while ( long process is not complete && 

(qmsg.msg != WM_QUIT) ) 

{ 

while ( WinPeekMsg (hab, &qmsg, 0L, 0L, 0L, PM_REMOVE) && 

(qmsg.msg != WM_QUIT) ) 

WinDispatchMsg (hab, &qmsg); 

if (qmsg.msg == WM_QUIT) 
continue; 

/* Perform long drawing */ 

} 

This loop enables the user to switch to another process or perform other actions while 
the long drawing process is occurring. Another option is to perfrom the long drawing 
operation in a separate thread. This is discussed in Chapter 12, “Threads and Semaphores.” 

Message filtering is a feature of WinPeekMsg, WinGetmsg, and WinWaitMsg that 
allows an application to select a specific range of messages or messages destined for a par¬ 
ticular window. When a message filter is used, only those messages that satisfy the 
criteria specified are returned. Message filtering is frequently used to look ahead in the 
message queue or to remove a certain type of message. The message range is specified by 
the msgFilterFirst and msgFilterLast parameters. If hwndFilter is specified, only 
those messages posted to hwndFilter or its descendants are retrieved. For example, to 
filter for all mouse messages for any window, you can use the following: 

if (WinPeekMsg (hab, &qmsg, 0L, WMJVIOUSEFIRST, WM_MOUSELAST, 
PM_NOREMOVE)) 

Care must be taken when using message filtering with WinGetMsg or WinWaitMsg. 
You must be certain that a message satisfying the criteria can be placed in the queue or 
else these functions will never return. If you are interested only in determining whether 
a particular type of message is in the queue, a method more efficient than message filter¬ 
ing is to use the WinQueryQueueStatus function: 

ULONG APIENTRY WinQueryQueueStatus(HWND hwndDesktop); 
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The return value from WinQueryQueueStatus contains flags indicating the types of 
messages that are currently in the queue. The following flags are used: 


QS_KEY 

QS_MOUSEBUTT ON 

QS_MOUSEMOVE 

QS_MOUSE 

QS_TIMER 

QS_PAINT 

QS_POSTMSG 

QS_SEM1 

QS_SEM2 

QS_SEM3 

QS_SEM4 

QS_SENDMSG 


WM_CHAR message (s). 

Mouse button message(s). 
WM_MOUSEMOVE message(s). 
Mouse button or WM_MOUSEMOVE 
message (s). 

WM_TIMER message(s). 

WM_PAINT message (s). 

Message posted by the WinPostMsg 
function. 

WM_SEM1 message(s). 

WM_SEM2 message(s). 

WM_SEM3 message(s). 

WM_SEM4 message(s). 

Message sent from another application. 


To check quickly whether there are any mouse button messages, you use the 
following: 


if (WinQueryQueueStatus (HWND_DESKTOP) & QS_MOUSEBUTTON) 

At this point, if you are interested in retrieving mouse button messages, you can call 
WinPeekMsg or WinGetMsg with a mouse button filter (WM_BUTT0N1 DOWN , 
WM_BUTTON LAST), knowing that a mouse button message will be returned. 

Messages are retrieved from the message queue based on a predefined priority. Mes¬ 
sages of a higher priority are returned before messages with a lower priority. 


Priority 


Message 


1 

2 

3 

4 

5 

6 

7 

8 


WM_SEM1. 

Messages posted with WinPostMsg. 
Keyboard and mouse messages. 
WM_SEM2. 

WM_PAINT. 

WM_SEM3. 

WM_TIMER. 

WM_SEM4. 


Looking at the priorities, you will always retrieve input messages before WM_PAINT 
messages, and you will always retrieve WM_PAINT messages before WM_TIMER messages. 
Notice that messages posted with WinPostMsg are assigned a priority of 2 even if the 
message your application posts is WM_TIMER. 
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WM_USER Messages 

Your application is not restricted to using only the messages defined by PM. You can 
define your own application messages. The predefined message identifier WMJJSER has 
been set aside for you to define your own messages. You should not define messages with 
a value less than WMJJSER (0x1000), but are free to define messages above this value. 
Typically, this is done by adding values to WMJJSER as shown here: 

#define WM_USER_POSITION WM_USER+1 

#define WM_USER_CHILDACTIVATE WMJJSER+2 

Multiple Document Interface Application 

Now, you put all this information to use by creating a sample application. The sample 
application will be a basic Multiple Document Interface (MDI) application with a float¬ 
ing toolbar. MDI applications are a main application window that contains multiple child 
windows, all managed by the main window. The main window handles the creation, 
arrangement, activation, and destruction of the child windows. Figure 3.11 illustrates 
the MDI window for the sample application. It contains two MDI child windows and a 
floating toolbar window. 

Figure 3.11. 
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The sample will use most of the concepts discussed in this chapter including window 
enumeration, Z-order maintenance, frame window subclassing, window data, window 
sizing and positioning, application and window activation, and window tracking. 

We begin by defining the resources that will be used. The resource file MINIMDI.RC 
contains the definitions for the icons, pointers, stringtable, menus, and dialogs. 
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MINIMDI.RC 


/* 


MiniMDI Resource File 


Chapter 3 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


#include <os2.h> 


#include 

i "minimdi.h" 


/* Icons 

; */ 


ICON 

ID_APPNAME 

MINIMDI.ICO 

ICON 

ID_CHILDWINDOW 

CHILD.ICO 

ICON 

IDC_WININFO 

WININFO.ICO 

/* Pointers */ 


POINTER 

IDPTR HEART 

HEART.PTR 

POINTER 

IDPTR CLIENT 

CLIENT.PTR 

POINTER 

IDPTR_SYSMENU 

SYSMENU.PTR 

POINTER 

IDPTR MENU 

MENU.PTR 

POINTER 

IDPTR MINMAX 

MINMAX.PTR 

POINTER 

IDPTR_LEFT 

LEFT.PTR 

POINTER 

IDPTR_TOP 

TOP.PTR 

POINTER 

IDPTR_LEFTTOP 

LTOP.PTR 

POINTER 

IDPTR_RIGHTTOP 

RTOP.PTR 

POINTER 

IDPTR TITLEBAR 

TITLEBAR.PTR 

POINTER 

IDPTR POPUPMENU 

POPUP.PTR 


*/ 


STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "MiniMDI Application 

END 


MENU ID_APPNAME 

{ 

SUBMENU "-Window", 

{ 

MENUITEM "-New Child", 
MENUITEM "Ne~xt Child" 
MENUITEM "", 

MENUITEM "-Close All", 
MENUITEM "", 

MENUITEM "-About", 

} 

SUBMENU "-Arrange", 

{ 

MENUITEM "-Tile", 


IDMJVINDOW 

IDM_NEWCHILD 

IDM_NEXTCHILD 

-1, MIS_SEPARATOR 

IDM_CLOSEALL 

-1, MIS_SEPARATOR 

IDM_AB0UT 

IDM_ARRANGEMENU 

IDM TILE 
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MENUITEM "-Cascade", IDM_CASCADE 

MENUITEM "-Arrange Icons", I DISARRANGE 

} 

} 

rcinclude toolbar.dig 
rcinclude wininfo.dlg 
rcinclude ..\common\about.dig 


You use two dialogs in this application. One is used to display the toolbar window 
and the other is used to display the window information. 


TOOLBAR.DLG 


/* 


MiniMDI Toolbar Dialog 
Chapter 3 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_TOOLBAR LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Tools' 1 , IDD_TOOLBAR, 0, 0, 41, 133, NOT FS_DLGBORDER 
| FS_BORDER, 

FCF_TITLEBAR ] FCF_NOBYTEALIGN | FCF_NOMOVEWITHOWNER 


BEGIN 

PUSHBUTTON 

GROUPBOX 

LTEXT 

CONTROL 


LTEXT 

CONTROL 


LTEXT 

CONTROL 


”#200'', IDC_WININFO, 9, 115, 24, 18, WS_GROUP | 

WS_TABSTOP j BS_ICON 

"Color", -1, 1, 43, 40, 71 

"Red", -1, 5, 97, 20, 8 

PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

IDC_RED, 8, 88, 27, 12, WC_SPINBUTTON, 
SPBS_READONLY ] SPBS_NUMERICONLY | SPBS_MASTER | 
SPBS_JUSTRIGHT | SPBS_FASTSPIN | 

WS_GROUP | WS_TABSTOP ) WS_VISIBLE 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

"Green", -1, 5, 76, 28, 8 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

"", IDC_GREEN, 8, 67, 27, 12, WC_SPINBUTTON, 
SPBS_READONLY | SPBS_NUMERICONLY j SPBS_MASTER ] 
SPBS_JUSTRIGHT | SPBS_FASTSPIN j 
WS_GR0UP | WS_TABSTOP | WS_VISIBLE 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

"Blue", -1, 5, 55, 22, 8 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

IDC_BLUE, 8, 46, 27, 12, WC_SPINBUTTON, 
SPBS_READONLY | SPBS_NUMERICONLY | SPBS_MASTER | 
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SPBS_JUSTRIGHT j SPBS_FASTSPIN | 

WS_GR0UP | WS_TABSTOP | WS_VISIBLE 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv M 
GROUPBOX "Option", -1, 1, 0, 40, 42 
AUTOCHECKBOX “Move", IDCJ/IOVE, 4, 24, 35, 10, WS_GR0UP 

| WS_TABSTOP PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 
AUTOCHECKBOX "Track", IDC_TRACK, 4, 13, 35, 10, WS_GROUP 

| WS_TABSTOP PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 
AUTOCHECKBOX "Open", IDC_0PEN, 4, 2, 36, 10, WS_GROUP 

| WS_TABSTOP PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 


END 

END 


The Toolbar dialog was created by using the dialog editor that comes with the 
OS/2 toolkit with some changes made to the file. You want the toolbar to be capable of 
moving freely about the screen without much control from its owner. The FCF flags define 
the style for this dialog: 

DIALOG "Tools", IDD_TOOLBAR, 0, 0, 41, 133, NOT FS_DLGBORDER | FS_BORDER, 
FCF_TITLEBAR | FCF_NOBYTEALIGN j FCF_NOMOVEWITHOWNER 

The only frame control you want for the toolbar is the titlebar. You use the 
FCF_NOMOVEWITHOWNER flag mentioned earlier so that the toolbar window remains in its 
current position when its owner window is moved around the screen. The first control is 
a pushbutton control; however, you use a button style of BS_ICON. This defines a 
pushbutton as usual except that an icon, rather than text, is drawn on the button face. 

The icon to use is defined by the text in the format "#iconID". The iconID is the nu¬ 
meric identifier associated with the icon to use. In this case, it is the WININFO.ICO 
identified with id 200 (IDC_WININF0). The toolbar also contains a set of RGB controls 
to define the color mix for the child window. The Red, Green, and Blue values are en¬ 
closed in a group box with each color specified by a spinner (see Figure 3.12). For each 
control within the group box, you use a slightly smaller font, so we have defined a 
PRESPARAMS for each. The PRESPARAMS attribute enables you to define many presenta¬ 
tion parameter styles for the control: 

PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

This says that we want to use the Helv 8 point font for this control. Finally, we have 
three check boxes enclosed in another group box. These check boxes are used to set the 
three options that we have defined (see Figure 3.12). 
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Figure 3.12. 
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WININFO.DLG 


/* 


MiniMDI Winlnfo Dialog 
Chapter 3 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_WININFO LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 


DIALOG "Window Information", IDD_ 

WININFO, 

r-T 

CD 

62, 192, 51, 

WS_VISIBLE, FCF_SYSMENU 

| FCF_TITLEBAR 




BEGIN 







LTEXT 

"Title:", 

-1, 

6, 

39, 

22, 

8 

GROUPBOX 

"Position 

", -1, 

3, 

4, 

HI, 

30 

LTEXT 

"X:", 

-1, 

11, 

17, 

20, 

8 

LTEXT 

"Y:", 

-1, 

11, 

7, 

20, 

8 

LTEXT 

"Width:", 

-1, 

49, 

17, 

32, 

8 

LTEXT 

"Height:" 

, -1, 

49, 

7, 

32, 

8 

GROUPBOX 

"State", 

-1, 

125, 

18, 

57, 

16 

ENTRYFIELD 

ii ii 

IDC_TITLE, 

31, 

38, 

150, 

8, ES_MARGIN 


WS_GR0UP 

| WS_TABSTOP 





PUSHBUTTON 

"OK", 

DID_OK, 

124, 

3, 

40, 

13, 


WS_GROUP 

| WS_TABSTOP 





RTEXT 

"0000 ", 

IDC_XP0S, 

22, 

17, 

23, 

8 

RTEXT 

"0000", 

IDC_YP0S, 

22, 

7, 

23, 

8 

RTEXT 

"0000", 

IDC_WIDTH, 

81, 

17, 

25, 

8 

RTEXT 

"0000", 

IDC_HEIGHT, 

81, 

7, 

25, 

8 

LTEXT 

"Normal", 

IDC STATE, 

128, 

19, 

51, 

8 


END 

END 
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The Window Information dialog was also created using the dialog editor. The FCF 
flags define the styles for this dialog: 

DIALOG "Window Information", IDD_WININFO, 67, 62 , 192, 51, WS_VISIBLE, 
FCF_SYSMENU ] FCF_TITLEBAR 

This dialog is defined to contain a system menu and a titlebar. This dialog consists of 
several static control fields, an edit window, and a pushbutton. The edit window is used 
to display the child window text, and the pushbutton is used to accept the changes to the 
window text. We move now to the application code. 


MINIMDI.C 


/* 


MiniMDI Program 
Chapter 3 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCLJVIN 
#define INCL GPI 


#include <os2.h> 

#include <stdio.h> 

#include "minimdi.h" 

#include 11 . .\common\about. h" 

/* Window and Dialog Functions 
MRESULT EXPENTRY ClientWndProc 
MRESULT EXPENTRY ChildWndProc 
MRESULT EXPENTRY ToolBarDlgPro 
MRESULT EXPENTRY WinlnfoDlgPro 


*/ 

(HWND,ULONG,MPARAM,MPARAM) 
(HWND,ULONG,MPARAM,MPARAM) 
(HWND,ULONG,MPARAM,MPARAM) 
(HWND,ULONG,MPARAM,MPARAM) 


/* Window Subclass Functions */ 

MRESULT EXPENTRY ChildSubclassProc (HWND,ULONG,MPARAM,MPARAM) 
MRESULT EXPENTRY FrameSubclassProc (HWND,ULONG,MPARAM,MPARAM) 
MRESULT EXPENTRY MenuSubclassProc (HWND,ULONG,MPARAM,MPARAM) 
MRESULT EXPENTRY SysMenuSubclassProc (HWND,ULONG,MPARAM,MPARAM) 
MRESULT EXPENTRY TitleBarSubclassProc (HWND,ULONG,MPARAM,MPARAM) 


/* Local Functions */ 

VOID Arrangelcons (HWND); 

VOID CascadeChildWindows (HWND); 

VOID CenterWindow (HWND); 

VOID CloseAllChildWindows (HWND); 

VOID CreateChildWindow (HWND); 
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VOID GetNextWindowPos (ULONG, PSWP); 

VOID InitializeAppWindow (HWND); 

BOOL IsWindowMaximized (HWND); 

BOOL IsWindowMinimized (HWND); 

VOID PaintTitleBar (HWND, HPS); 

VOID SwitchToNextChildWindow (VOID); 

VOID TileChildWindows (HWND); 

/* Undocumented PM Functions */ 

extern BOOL APIENTRY Win32StretchPointer(HPS hps, SHORT x, SHORT y, 

SHORT cx, SHORT cy, HPOINTER hptr, USHORT fs); 

/* Undocumented WinDrawBorder Flags */ 

#define DB_RAISED 0x0400 

#define DB_CORNERBORDER 0x8000 

/* User-Defined messages */ 

#define WM_USER_POSITION WM_USER+1 

#define WM_USER_CHILDACTIVATE WM_USER+2 

/* User-Defined Window Extra Words */ 

#define QWL_COLOR_RGB QWL_USER 

#define QWL_MOVE QWL_COLOR_RGB + sizeof(ULONG) 

#define QWL_TRACKING QWL_MOVE + sizeof(BOOL) 

#define QWL_0PEN QWL_TRACKING + sizeof(BOOL) 

#define QWL_EXTRA QWL_OPEN + sizeof(BOOL) 

/* Global Variables */ 

HAB hab; 

HWND hWndFrame, 

hWndClient, 
hWndToolBar, 
hWndActiveChild; 

CHAR szTitle[64]; 


BOOL bAppIsActive = FALSE; 

ULONG ulNumChildren = 0L; 

ULONG ulNumMinChildren = 0L; 

/* Pointer Handles */ 

HPOINTER hPtrHeart = 0 ; 

HPOINTER hPtrClient = 0 ; 

HPOINTER hPtrSysMenu = 0 ; 

HPOINTER hPtrMenu = 0 ; 

HPOINTER hPtrMinMax = 0 ; 

HPOINTER hPtrLeft = 0 ; 

HPOINTER hPtrTop = 0 ; 

HPOINTER hPtrLeftTop = 0 ; 

HPOINTER hPtrRightTop = 0 ; 


/* ULONG */ 
/* BOOL */ 
/* BOOL */ 
/* BOOL */ 
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HPOINTER hPtrTitleBar = 0; 

HPOINTER hPtrPopupMenu = 0; 

/* Subclassed PM Window Callbacks */ 

PFNWP pfnFrameProc; /* Frame Window */ 

PFNWP pfnTitleBarProc; /* TitleBar Window */ 

PFNWP pfnSysMenuProc; /* System Menu Window */ 

PFNWP pfnMenuProc; /* Menu Window */ 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR j FCF_SYSMENU | FCF_ICON 

FCF_SIZEBORDER | FCF_MINMAX | FCF_MENU 
FCF_SHELLPOSITION | FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

/* Create the main application window */ 
hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

/* Subclass the frame control windows */ 
pfnFrameProc = WinSubclassWindow (hWndFrame, 

(PFNWP)FrameSubclassProc); 
pfnTitleBarProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_TITLEBAR), 

(PFNWP)TitleBarSubclassProc); 
pfnSysMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_SYSMENU), 
(PFNWP)SysMenuSubclassProc); 
pfnMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_MENU), 
(PFNWP)MenuSubclassProc); 

InitializeAppWindow (hWndClient); 

WinShowWindow (hWndFrame, TRUE); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 


m 
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WinDestroyWindow (hWndFrame); 
WinDestroyMsgQueue (hmq); 
WinTerminate (hab); 
return (0); 


/* . Local Functions .... */ 

VOID Arrangelcons (HWND hWnd) 

{ 

PSWP pSwp; 

/* Allocate memory to hold the SWP structures */ 
if (IDosAllocMem ((PPVOID)&pSwp, sizeof(SWP) * ulNumMinChildren, 
fALLOC)) 

{ 

HWND hWndChild; 

ULONG ulChildCnt; 

HENUM hEnum; 

ulChildCnt = 0; 

/* Begin child window enumeration */ 
hEnum = WinBeginEnumWindows (hWnd); 

/* Get handle to each child frame window */ 
while ((hWndChild = WinGetNextWindow (hEnum)) != 0) 

{ 

if ( IsWindowMinimized (hWndChild) ) 

{ 

pSwp[UlChildCnt].fl = SWP_MOVE | SWP_FOCUSDEACTIVATE; 

pSwp[ulChildCnt].x 

pSwp[ulChildCnt].y = 0; 

pSwp[ulChildCnt++].hwnd = hWndChild; 

/* Destroy the current minimize position -- a little 
PM trick */ 

WinSetWindowUShort (hWndChild 3 QWS_XMINIMIZE 3 (USHORT)-1); 
WinSetWindowUShort (hWndChild 3 QWS_YMINIMIZE 3 (USHORT)- 1 ); 

} 

/* End child window enumeration */ 

WinEndEnumWindows (hEnum); 

/* Arrange the iconic windows */ 

WinSetMultWindowPos (hab 3 pSwp 3 ulChildCnt); 

/* Free the allocated memory */ 

DosFreeMem ((PVOID)pSwp); 
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return; 


VOID CascadeChildWindows (HWND hWnd) 

{ 

PSWP pSwp; 

ULONG ulChildCnt = (ulNumChildren - ulNumMinChildren); 

/* Allocate memory to hold the SWP structures */ 

if ('DosAllocMem ((PPVOID)&pSwp, sizeof(SWP) * ulChildCnt, fALLOC)) 

{ 

HWND hWndChild; 
ulChildCnt = 0L; 

/* Query the bottommost child frame window in the z-order */ 
hWndChild = WinQueryWindow (hWnd, QW_BOTTOM); 

while (hWndChild) 

{ 

/* Skip ICONTEXT windows and minimized windows */ 
if ( WinQueryWindowUShort (hWndChild, QWS_ID) && 

!IsWindowMinimized (hWndChild) ) 

{ 

GetNextWindowPos (ulChildCnt, &pSwp[ulChildCnt]); 
pSwp[ulChildCnt].fl = SWP_MOVE J SWP_SIZE j SWP_SHOW; 

/* If child is maximized then restore it */ 
if (IsWindowMaximized (hWndChild)) 

pSwp[ulChildCnt].fl |= SWP_RESTORE; 

pSwp[ulChildCnt++].hwnd = hWndChild; 

} 

/* Query the previous child frame window in the z-order */ 
hWndChild = WinQueryWindow (hWndChild, QW_PREV); 

} 

/* Arrange the cascaded windows */ 

WinSetMultWindowPos (hab, pSwp, ulChildCnt); 

/* Free the allocated memory */ 

DosFreeMem ((PVOID)pSwp); 

} 

return; 



} 
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VOID CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd,&Rectl); 

WinSetWindowPos (hWnd, HWND_TOP, (ulScrWidth-Recti.xRight)/2, 
(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_MOVE | SWP_ACTIVATE); 
return; 


VOID CloseAllChildWindows (HWND hWnd) 

{ 

HWND hWndChild; 

HENUM hEnum; 

/* Begin child window enumeration */ 
hEnum = WinBeginEnumWindows (hWnd); 

/* Get handle to each child frame window */ 
while ((hWndChild = WinGetNextWindow (hEnum)) != 0) 
WinDestroyWindow (hWndChild); 

/* End child window enumeration */ 

WinEndEnumWindows (hEnum); 

return; 

} 

VOID CreateChildWindow (HWND hWnd) 

{ 

HWND hWndChild; 

HWND hWndChildFrame; 

CHAR szTitle[23]; 

ULONG fIChildFrameFlags = FCF_TITLEBAR J FCF_SYSMENU ] FCF_ICON ] 

FCF_SIZEBORDER | FCF_MINMAX | 
FCF_NOBYTEALIGN; 

if ((hWndChildFrame = WinCreateStdWindow (hWnd, 0L, 

&fIChildFrameFlags, 

"CHILD", ,,M , 0L, 0L, I D_CH ILDWINDOW, &hWndChild)) != 0) 

{ 

SWP Swp; 

/* If the currently active child is maximized restore it */ 
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if (hWndActiveChild && IsWindowMaximized (hWndActiveChild)) 
WinSetWindowPos (WinQueryWindow (hWndActiveChild, QW_PARENT), 

0L, 0L, 0L, 0L, 0L, SWP_RESTORE); 

WinSetOwner (hWndChild, hWndChildFrame); 

sprintf (szTitle, "Child Window %04x:%04x", 

HIUSHORT(hWndChildFrame), LOUSHORT(hWndChildFrame)); 
WinSetWindowText (hWndChildFrame, szTitle); 

GetNextWindowPos (ulNumChildren - 1L, &Swp); 

WinSetWindowPos (hWndChildFrame, 0L, Swp.x, Swp.y, Swp.cx, Swp.cy, 
SWP_M0VE | SWP_SIZE j SWP_SHOW | SWP_ACTIVATE); 

/* Force a repaint of the titlebar window */ 

WinlnvalidateRect (WinWindowFromID(hWndFrame,FID_TITLEBAR), 

NULL, FALSE); 


return; 


VOID GetNextWindowPos (ULONG ulCnt, PSWP pSwp) 

{ 

RECTL Recti; 

ULONG ulXDiff, 
ulYDiff, 

ulWindowsPerStack; 

WinQueryWindowRect (hWndClient, &Rectl); 
if (ulNumMinChildren) 

Recti.yBottom += WinQuerySysValue (HWND_DESKTOP, SV_CYICON) * 2; 

UlXDiff = WinQuerySysValue (HWND_DESKTOP, SV_CXSIZEBORDER) + 
WinQuerySysValue (HWND_DESKTOP, SV_CXMINMAXBUTTON) / 2; 
ulYDiff = WinQuerySysValue (HWND_DESKTOP, SV_CYSIZEBORDER) + 
WinQuerySysValue (HWND_DESKTOP, SV_CYMINMAXBUTTON); 

ulWindowsPerStack = (Recti.yTop - Recti.yBottom) / (3 * ulYDiff); 
pSwp->cx = Recti.xRight - (ulWindowsPerStack * ulXDiff); 
pSwp->cy = (Recti.yTop - Recti.yBottom) - 
(ulWindowsPerStack * ulYDiff); 
ulWindowsPerStack++; 

pSwp->x = (ulCnt % ulWindowsPerStack) * ulXDiff; 
pSwp->y = Recti.yTop - pSwp->cy - 

((ulCnt % ulWindowsPerStack) * ulYDiff); 

return; 
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VOID InitializeAppWindow (HWND hWnd) 

{ 

WinRegisterClass (hab, "CHILD", ChildWndProc, 0, QWL_EXTRA); 

hWndToolBar = WinLoadDlg (HWND_DESKTOP, hWnd, ToolBarDlgProc, 
0L, IDD_TOOLBAR, NULL); 

/* Create three children initially */ 

CreateChildWindow (hWnd); 

CreateChildWindow (hWnd); 

CreateChildWindow (hWnd); 

WinPostMsg (hWndToolBar, WM_USER_POSITION, 0L, 0L); 

WinPostMsg (hWnd, WM_COMMAND, (MPARAM)IDM_TILE, 0L); 
return; 

} 

BOOL IsWindowMaximized (HWND hWnd) 

{ 

/* If hWnd is the client window, query the frame window 
(ie. the parent) */ 

if (WinQueryWindowUShort (hWnd, QWS_ID) == FID_CLIENT) 
hWnd = WinQueryWindow (hWnd, QW_PARENT); 
return (WinQueryWindowULong (hWnd, QWL_STYLE) & WS_MAXIMIZED) 


BOOL IsWindowMinimized (HWND hWnd) 

{ 

if (WinQueryWindowUShort (hWnd, QWS_ID) == FID_CLIENT) 
hWnd = WinQueryWindow (hWnd, QW_PARENT); 
return (WinQueryWindowULong (hWnd, QWL_STYLE) & WS_MINIMIZED) 

} 

VOID PaintTitleBar (HWND hWnd, HPS hps) 

{ 

RECTL Recti; 

BOOL bActive; 

SHORT Scale, 

X; 

ULONG inx; 

/* If window is not visible then nothing to paint */ 
if (IWinlsWindowVisible (hWnd)) 
return; 

/* Get the current active state of the titlebar */ 
bActive = (BOOL)(WinQueryWindowULong (hWnd, QWLJJSER) & 1); 

/* Draw the correct border for the titlebar */ 
WinQueryWindowRect (hWnd, &Rectl); 
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WinDrawBorder (hps, &Rectl, bActive ? 0L : 1L, 1L, 
SYSCLR_TITLEBOTTOM, 

bActive ? SYSCLR_ACTIVETITLE : SYSCLR_INACTIVETITLE, 

DB_RAISED | DB_CORNERBORDER j DB_STANDARD | DB_INTERIOR); 

/* Draw a heart for each child window that exists. 

Scale the pointer to fit in the titlebar height minus 2 minus 
the nominal border width times 2. 

Since the WC_TITLEBAR class is not CS_CLIPSIBLINGS, it is 
possible to write over the minmax window. Only output as many 
hearts as will fit in the titlebar window. 

Use the Win32StretchPointer API so we get a transparent bitbit.*/ 

Scale = (SHORT)(Recti.yTop - Recti.yBottom - 2 - 

2 * WinQuerySysValue (HWND_DESKTOP, SV_CYBORDER)); 

if (bAppIsActive) 

{ 

if ((inx = ulNumChildren) != 0) 

{ 

X = (SHORT)(WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) +1); 
while ( inx && ((LONG)(X + Scale) < Recti.xRight) ) 

{ 

Win32StretchPointer (hps, X, 2, Scale, Scale, hPtrHeart, 
DP_NORMAL); 
inx--; 

X += (SHORT)(Scale + 2); 

} 

} 

else 

{ 

POINTL Ptl; 

Ptl.x = WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) + 1; 

Ptl.y = 2; 

GpiCharStringAt (hps, &Ptl, 21L, (PSZ)"MiniMDI - No children"); 

} 

} 

else 

{ 

POINTL Ptl; 

Ptl.x = WinQuerySysValue (HWND_DESKTOP, SV_CXBORDER) + 1; 

Ptl.y = 2; 

GpiCharStringAt (hps, &Ptl, 20L, (PSZ)"MiniMDI - Not Active"); 


return; 


VOID SwitchToNextChildWindow () 
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{ 

HWND hWndNext, 

hWndActiveFrame; 

hWndNext 

hWndActiveFrame = WinQueryWindow (hWndActiveChild, QW_PARENT); 

/* We need to query the next until we find a 
non-WC_ICONTEXT window */ 

while ( ((hWndNext = WinQueryWindow (hWndNext, QW_NEXT)) != 0) && 
!WinQueryWindowUShort (hWndNext, QWS_ID)) 

{ 

/* Do Nothing */ 

} 

if (hWndNext) 

{ 

/* If current active child is maximized then restore it */ 
WinSetWindowPos (hWndNext, HWND_T0P, 0, 0, 0, 0, 

SWP_ZORDER | SWP_ACTIVATE); 

WinSetWindowPos (hWndActiveFrame, HWND_BOTTOM, 0, 0, 0, 0, 
IsWindowMaximized (hWndActiveFrame) ? 

SWP_RESTORE | SWP_ZORDER : SWP_ZORDER); 


return; 


VOID TileChildWindows (HWND hWnd) 

{ 

PSWP pSwp; 

ULONG ulChildCnt = (ulNumChildren - ulNumMinChildren); 

/* Allocate memory to hold the SWP structures */ 

if (IDosAllocMem ((PPVOID)&pSwp, sizeof(SWP) * ulChildCnt, fALLOC)) 

{ 

ULONG ulSquare, 
ulNumRows, 
ulNumCols, 
ulExtraCols, 
ulWidth, 
ulHeight; 

RECTL Recti; 

HWND hWndChild; 

for (ulSquare = 2; ulSquare * ulSquare <= ulChildCnt; ulSquare++); 

{} 

ulNumCols = ulSquare - 1 ; 

ulNumRows = ulChildCnt / ulNumCols; 
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ulExtraCols = ulChildCnt % ulNumCols; 

WinQueryWindowRect (hWnd, &Rectl); 
if (ulNumMinChildren) 

Recti.yBottom += WinQuerySysValue (HWND_DESKTOP, SV_CYIC0N) * 2; 
if (Recti.xRight > 0L && (Recti.yBottom < Recti.yTop)) 

{ 

HENUM hEnum; 

/* Begin child window enumeration */ 
hEnum = WinBeginEnumWindows (hWnd); 

/* Get handle to each child frame window */ 
if ((hWndChild = WinGetNextWindow (hEnum)) != 0) 

{ 

ULONG ulCurRow, 
ulCurCol; 

ulChildCnt = 0L; 

ulHeight = (Recti.yTop - Recti.yBottom) / ulNumRows; 

for (ulCurRow = 0; ulCurRow < ulNumRows; ulCurRow++) 

{ 

if ((ulNumRows - ulCurRow) <= ulExtraCols) 
ulNumCols++; 

for (ulCurCol = 0; ulCurCol < ulNumCols; ulCurCol++) 

{ 

ulWidth = Recti.xRight / ulNumCols; 

/* Skip ICONTEXT windows and minimized windows */ 
while ( hWndChild && 

( IWinQueryWindowUShort (hWndChild, QWS__ID) | j 
IsWindowMinimized (hWndChild) ) ) 
hWndChild = WinGetNextWindow (hEnum); 

if (hWndChild) 

{ 

pSwp[ulChildCnt].fl 

SWPJVIOVE | SWP_SIZE | SWP_SHOW; 

/* If child is maximized, then restore it */ 
if (IsWindowMaximized (hWndChild)) 

pSwp[ulChildCnt].fl |= SWP_RESTORE; 

pSwp[ulChildCnt].x = ulWidth * ulCurCol; 

pSwp[ulChildCnt].y 

Recti.yTop - (ulHeight * (ulCurRow +1)); 
pSwp[ulChildCnt].cx = ulWidth; 
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pSwp[ulChildCnt].cy = ulHeight; 
pSwp[ulChildCnt++].hwnd = hWndChild; 

/* Get handle to next child frame window */ 
hWndChild = WinGetNextWindow (hEnum); 

} 

} 

if ((ulNumRows - ulCurRow) <= ulExtraCols) 

{ 

ulNumCols- -; 
ulExtraCols- -; 

} 

} 

} 

/* End child window enumeration */ 

WinEndEnumWindows (hEnum); 

} 

/* Arrange the tiled windwos */ 

WinSetMultWindowPos (hab, pSwp, ulChildCnt); 

/* Free the allocated memory */ 

DosFreeMem ((PVOID)pSwp); 


return; 

} 


/* 


Window and Dialog Functions 


*/ 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

RECTL Recti; 

HPS hps; 


switch (msg) 

{ 

case WM_CREATE: 
hPtrHeart 
hPtrClient 
hPtrSysMenu 
hPtrMenu 
hPtrMinMax 
hPtrLeft 


= WinLoadPointer(HWND_DESKTOP,0L,IDPTR_HEART); 

= WinLoadPointer(HWND_DESKTOP, 0L,IDPTR_CLIENT); 

= WinLoadPointer(HWND_DESKTOP,0L,IDPTR_SYSMENU); 
= WinLoadPointer(HWND_DESKTOP,0L,IDPTR_MENU); 

= WinLoadPointer(HWND_DESKTOP,0L 3 IDPTR_MINMAX); 

= WinLoadPointer(HWND_DESKTOP,0L,IDPTR_LEFT); 
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hPtrTop 

hPtrLeftTop 

hPtrRightTop 

hPtrTitleBar 

hPtrPopupMenu 

break; 


WinLoadPointer(HWND_DESKTOP,0L,IDPTR_TOP); 
WinLoadPointer(HWND_DESKTOP,0L,IDPTR_LEFTTOP); 
WinLoadPointer(HWND_DESKTOP,0L,IDPTR_RIGHTTOP); 
WinLoadPointer(HWND_DESKTOP, 0L,IDPTR_TITLEBAR); 
WinLoadPointer(HWND_DESKTOP,0L,IDPTR_POPUPMENU) 


case WM_M0USEM0VE: 

WinSetPointer (HWND_DESKTOP, hPtrClient); 
break; 


case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 

WinFillRect (hps, &Rectl, CLRJVHITE); 

WinEndPaint (hps); 
mReturn = 0L; 
break; 

case WM_FOCUSCHANGE: 

if ( WinQueryWindowULong (hWnd, QWL_HMQ) != 

WinQueryWindowULong ((HWND)mpl, QWL_HMQ) ) 

{ 

if (SHORT1FROMMP(mp2)) 

/* Application is gaining activation */ 
bAppIsActive = TRUE; 
else 

/* Application is losing activation */ 
bAppIsActive = FALSE; 

/* Force a repaint of the titlebar window */ 
WinlnvalidateRect (WinWindowFromlD(hWndFrame,FID_TITLEBAR), 
NULL, FALSE); 

} 

bHandled = FALSE; 
break; 

case WM_INITMENU: 

if (SH0RT1FROMMP(mpl) == IDM_ARRANGEMENU) 

{ 

BOOL bEnable = (ulNumChildren != ulNumMinChildren); 
WinEnableMenuItem ((HWND)mp2, IDM_TILE, bEnable); 
WinEnableMenuItem ((HWND)mp2, IDM_CASCADE, bEnable); 
WinEnableMenuItem ((HWND)mp2, IDM_ARRANGE, ulNumMinChildren) 

} 

else if (SH0RT1FROMMP(mpl) == IDM_WINDOW) 

{ 

WinEnableMenuItem ((HWND)mp2, IDM_NEXTCHILD, 
ulNumChildren >1); 
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WinEnableMenuItem ((HWND)mp2, IDM_CLOSEALL, 
ulNumChildren); 

} 

break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_NEWCHILD: 

CreateChildWindow (hWnd); 
break; 

case IDM_NEXTCHILD: 
if (hWndActiveChild) 
SwitchToNextChildWindow (); 
break; 


case IDM_TILE: 
TileChildWindows (hWnd); 
break; 

case IDM_CASCADE: 

CascadeChildWindows (hWnd); 
break; 

case IDM_ARRANGE: 

Arrangelcons (hWnd); 
break; 

case IDM_CLOSEALL: 

CloseAllChildWindows (hWnd); 
break; 


case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

break; 


case WM_DESTROY: 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 
WinDestroyPointer 


(hPtrHeart); 
(hPtrClient); 
(hPtrSysMenu); 
(hPtrMenu); 
(hPtrMinMax); 
(hPtrLeft); 
(hPtrTop); 
(hPtrLeftTop); 
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WinDestroyPointer (hPtrRightTop); 
WinDestroyPointer (hPtrTitleBar); 
WinDestroyPointer (hPtrPopupMenu); 
break; 

default: 

bHandled - FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 
return (mReturn); 


MRESULT EXPENTRY ChildWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0L; 

ULONG ulColorRGB; 

PSWP pSwp; 

RECTL Recti; 

HPS hps; 

switch (msg) 

{ 

case WM_CREATE: 

/* Initialize window extra words */ 

WinSetWindowULong (hWnd, QWL_COLOR_RGB, 0X00FFFFFF); 
WinSetWindowULong (hWnd, QWL_M0VE, TRUE); 

WinSetWindowULong (hWnd, QWLJTRACKING, FALSE); 
WinSetWindowULong (hWnd, QWL_OPEN, TRUE); 

ulNumChildren++; 

/* If this is first child window, then enable the toolbar */ 
if (ulNumChildren == 1) 

WinEnableWindow (hWndToolBar, TRUE); 
break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 

/* Set color state in the hps to RGB mode */ 
GpiCreateLogColorTable (hps, LCOL_RESET, LCOLF_RGB, 0L, 0L, 
NULL); 

ulColorRGB = WinQueryWindowULong (hWnd, QWL_C0L0R_RGB); 
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WinFillRect (hps, &Rectl, ulColorRGB); 

WinEndPaint (hps); 
break; 

case WM_MINMAXFRAME: 
pSwp = (PSWP)mpl; 

/* Are we becoming minimized? */ 
if (pSwp->fl & SWP_MINIMIZE) 
ulNumMinChildren++; 
else 
{ 

/* hWnd is the client window handle -- use the frame */ 

HWND hWndFrame = WinQueryWindow (hWnd, QW_PARENT); 

if (IsWindowMinimized (hWndFrame)) 

{ 

/* Is the child window allowed to restore itself? */ 
if (WinQueryWindowllLong (hWnd, QWLJDPEN)) 

{ 

ulNumMinChildren- -; 

WinSetWindowUShort (hWndFrame, QWS_XMINIMIZE, (USHORT)-1); 
WinSetWindowUShort (hWndFrame, QWS_YMINIMIZE, (USHORT)-1); 

} 

else 

{ 

/* Don't allow the window to restore itself. 

Reset the window position */ 

WinQueryWindowPos (hWndFrame, pSwp); 
mReturn = (MRESULT)TRUE; 

} 

} 

} 

break; 

case WM_ACTIVATE: 

if (SHORT1FROMMP(mpl)) 

{ 

hWndActiveChild = hWnd; 

/* Notify toolbar of new active child window */ 

WinSendMsg (hWndToolBar, WM_USER_CHILDACTIVATE, 0L, 0L); 

} 

break; 

case WM_CL0SE: 

/* Don't let the WM_CL0SE go to WinDefWindowProc. The default 
processing for this is to post a WM_QUIT message to the 
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application. Since this is a child closing we don't want 
that to occur -- just destroy the window. */ 
WinDestroyWindow (WinQueryWindow (hWnd, QW_PARENT)); 
break; 

case WM_DESTROY: 

if (IsWindowMinimized (hWnd)) 
ulNumMinChildren- -; 

ulNumChildren - -; 

/* If there are no children left then disable the toolbar */ 
if (ulNumChildren == 0) 

WinEnableWindow (hWndToolBar, FALSE); 

/* Force a repaint of the titlebar window */ 
WinlnvalidateRect (WinWindowFromID(hWndFrame,FIDJTITLEBAR), 
NULL, FALSE); 
break; 

default: 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 
break; 


return (mReturn); 

> 

MRESULT EXPENTRY ToolBarDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0L; 

BOOL bHandled = TRUE; 

HWND hWndOwner; 

RECTL Recti; 

switch (msg) 

{ 

case WM_INITDLG: 

WinSendDlgltemMsg (hWnd, IDC_RED, SPBM_SETTEXTLIMIT, 

(MPARAM)3, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDC_RED, SPBM_SETLIMITS, 

(MPARAM)255L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_BLUE, SPBM_SETTEXTLIMIT, 
(MPARAM)3, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDC_BLUE, SPBM_SETLIMITS, 

(MPARAM)255L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_GREEN, SPBM_SETTEXTLIMIT, 
(MPARAM)3, (MPARAM)0); 
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WinSendDlgltemMsg (hWnd, IDC_GREEN, SPBM_SETLIMITS, 

(MPARAM)255L, (MPARAM)0L); 

WinSetFocus (HWND_DESKTOP, WinWindowFromID (hWnd, IDC_WININFO)); 
break; 

case WM_USER_POSITION: 

/* Position the toolbar in the lower-left corner of the owner */ 
hWndOwner = WinQueryWindow (hWnd, QW_OWNER); 

WinQueryWindowRect (hWndOwner, &Rectl); 

WinMapWindowPoints (hWndOwner, HWND_DESKTOP, 

(PPOINTL)&Rectl, 1L); 

WinSetWindowPos (hWnd, 0, Recti.xLeft, Recti.yBottom, 0L, 0L, 
SWP_M0VE | SWP_SHOW); 
break; 

case WM_USER_CHILDACTIVATE: 

{ 

ULONG ulRGB = WinQueryWindowULong (hWndActiveChild, 
QWL_C0L0R_RGB); 

WinCheckButton (hWnd, IDC_MOVE, 

(USHORT)WinQueryWindowULong (hWndActiveChild, 

QWL__M0VE)) ; 

WinCheckButton (hWnd, IDCJRACK, 

(USHORT)WinQueryWindowULong (hWndActiveChild, 

QWL_TRACKING)); 

WinCheckButton (hWnd, IDC_0PEN, 

(USHORT)WinQueryWindowULong (hWndActiveChild, 

QWL_0PEN)); 

WinSendDlgltemMsg (hWnd, IDC_RED, SPBM_SETCURRENTVALUE, 
(MPARAM)((UlRGB & 0X00FF0000) » 16), (MPARAM)0L); 
WinSendDlgltemMsg (hWnd, IDC_GREEN, SPBM_SETCURRENTVALUE, 
(MPARAM)((UlRGB & 0X0000FF00) » 8), (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_BLUE, SPBM_SETCURRENTVALUE, 
(MPARAM)(ulRGB & 0X000000FF), (MPARAM)0L); 

} 

break; 

case WM_C0NTR0L: 

if (hWndActiveChild) 

{ 

BOOL bChecked; 

switch (SHORT1FROMMP(mpl)) 

{ 

case IDCJVIOVE: 

if (SH0RT2FR0MMP(mpl) == BN_CLICKED) 

{ 

bChecked = WinQueryButtonCheckstate (hWnd, IDC_M0VE); 
WinSetWindowULong (hWndActiveChild, QWL_MOVE, bChecked); 
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WinSubclassWindow ( 

WinQueryWindow (hWndActiveChild, QW_PARENT), 
(PFNWP)ChildSubclassProc); 

} 

break; 

case IDC_TRACK: 

if (SH0RT2FR0MMP(mpl) == BN_CLICKED) 

{ 

bChecked = WinQueryButtonCheckstate (hWnd, IDC_TRACK); 
WinSetWindowULong (hWndActiveChild, QWL_TRACKING, 
bChecked); 

WinSubclassWindow ( 

WinQueryWindow (hWndActiveChild, QW_PARENT), 
(PFNWP)ChildSubclassProc); 

} 

break; 

case IDC_OPEN: 

if (SH0RT2FR0MMP(mpl) == BN_CLICKED) 

{ 

bChecked = WinQueryButtonCheckstate (hWnd, IDC_0PEN); 
WinSetWindowULong (hWndActiveChild, QWL_OPEN, bChecked) 

} 

break; 

case IDC_RED: 
case IDC_GREEN: 
case IDC_BLUE: 

if (SH0RT2FR0MMP(mpl) == SPBN_ENDSPIN) 

{ 

ULONG ulRed, 

ulGreen, 

ulBlue; 

WinSendDlgltemMsg (hWnd, IDC_RED, 

SPBM_QUERYVALUE, (MPARAM)&ulRed, 0L); 
WinSendDlgltemMsg (hWnd, IDC_GREEN, 

SPBM_QUERYVALUE, (MPARAM)&ulGreen, 0L); 
WinSendDlgltemMsg (hWnd, IDC_BLUE, 

SPBM_QUERYVALUE, (MPARAM)&ulBlue, 0L); 
WinSetWindowULong (hWndActiveChild, QWL_C0L0R_RGB, 
(ulRed « 16) | (ulGreen « 8) | ulBlue); 


/* Force the child to repaint NOW */ 
WinlnvalidateRect (hWndActiveChild, NULL, FALSE); 
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WinUpdateWindow (hWndActiveChild); 

} 

break; 

} 

} 

break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_WININFO: 
if (hWndActiveChild) 

{ 

WinEnableWindow (hWndFrame, FALSE); 

WinDlgBox (HWND_DESKTOP, hWnd, WinlnfoDlgProc, 

0L, IDD_WININFO, NULL); 

WinEnableWindow (hWndFrame, TRUE); 

} 

break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 

} 

MRESULT EXPENTRY WinlnfoDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0; 

BOOL bHandled = TRUE; 

CHAR szTitle[40]; 

HWND hWndActiveFrame; 

POINTL Ptl; 

SWP Swp; 

switch (msg) 

{ 

case WM_INITDLG: 

CenterWindow (hWnd); 

hWndActiveFrame = WinQueryWindow (hWndActiveChild, QW_PARENT); 
WinQueryWindowText (hWndActiveFrame, sizeof(szTitle), szTitle); 
WinQueryWindowPos (hWndActiveFrame, &Swp); 
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Ptl.x = Swp.x; 

Ptl.y = Swp.y; 

WinMapWindowPoints (hWndActiveFrame, hWndFrame, &Ptl, 1L); 


EM SETTEXTLIMIT, 


WinSendDlgltemMsg (hWnd, IDC_TITLE, 

(MPARAM)sizeof(szTitle), 0L); 

WinSetDlgltemText (hWnd, IDC_TITLE, 
WinSetDlgltemShort (hWnd, IDC_XP0S, 
WinSetDlgltemShort (hWnd, IDC_YP0S, 
WinSetDlgltemShort (hWnd, IDCJ/VIDTH, 
WinSetDlgltemShort (hWnd, IDC_HEIGHT, 
if (Swp.fl & SWP_MINIMIZE) 

WinSetDlgltemText (hWnd, IDC_STATE, 
else if (Swp.fl & SWP_MAXIMIZE) 

WinSetDlgltemText (hWnd, IDC_STATE, "Maximized") 

else 


szTitle); 

(SHORT)Ptl.x, 
(SHORT)Ptl.y, 
(USHORT)Swp.cx , 
(USHORT)Swp.cyj 


"Minimized"): 


TRUE); 
TRUE); 
FALSE); 
FALSE); 


WinSetDlgltemText (hWnd, IDC_STATE, "Normal"); 

WinSetFocus (HWND_DESKTOP, WinWindowFromID (hWnd, IDC_TITLE)); 
break; 


case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case DID_0K: 

WinQueryDlgltemText (hWnd, IDC_TITLE, sizeof(szTitle), 
szTitle); 

WinSetWindowText ( 

WinQueryWindow (hWndActiveChild, QW_PARENT), szTitle); 
WinDismissDlg (hWnd, DID_0K); 
break; 

} 

break; 


default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 


return (mReturn); 

} 

/* . Window Subclass Functions . */ 


MRESULT EXPENTRY ChildSubclassProc 

{ 


(HWND hWnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


BOOL 


bHandled = FALSE; 
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MRESULT mReturn = 0L; 

switch (msg) 

{ 

case WM_TRACKFRAME: 

if ( ((SHORT1FROMMP(mp1 ) & TFJ/IOVE) == TFJVIOVE) && 

!WinQueryWindowULong ( 

WinWindowFromID (hWnd, FID_CLIENT), QWL_M0VE)) 
bHandled = TRUE; 
break; 


case WM_QUERYTRACKINFO: 
if (WinQueryWindowULong ( 

WinWindowFromID (hWnd, FID_CLIENT), QWL_TRACKING)) 

{ 

PTRACKINFO pti; 

RECTL Recti; 


/* Let the PM frame window function initialize TRACKINFO */ 
mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 


} 


} 


WinQueryWindowRect (hWnd 
pti 

pti->ptlMinTrackSize.x = 
pti->ptlMinTrackSize.y = 
pti->ptlMaxTrackSize.x = 
pti->ptlMaxTrackSize.y = 
bHandled = TRUE; 


&Rectl); 

(PTRACKINFO)mp2; 
75L; 

50L; 

Recti.xRight + 40; 
Recti.yTop + 40; 


if (!bHandled) 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
return (mReturn); 


MRESULT EXPENTRY FrameSubclassProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0L; 

HPOINTER hPtr; 

switch (msg) 

{ 

case WM_CONTROLPOINTER: 
switch (SHORT1FROMMP(mpl)) 

{ 

case FID_SYSMENU: 

mReturn = (MRESULT)hPtrSysMenu; 
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break; 

case FID_MENU: 

mReturn = (MRESULT)hPtrMenu; 
break; 

case FIDJ/IINMAX: 

mReturn = (MRESULT)hPtrMinMax; 
break; 

default: 

mReturn = mp2; /* Use the default pointer */ 

} 

break; 

case WM_M0USEM0VE: 

switch (SH0RT1FROMMP(mp2)) 

{ 

case TF_LEFT: 

case TF_RIGHT: 
hPtr = hPtrLeft; 
break; 

case TF_TOP: 

case TF_BOTTOM: 
hPtr = hPtrTop; 
break; 

case TF_LEFT J TF_TOP: 

case TF_RIGHT j TF_B0TT0M: 
hPtr = hPtrLeftTop; 
break; 

case TF_RIGHT | TF_T0P: 

case TF_LEFT | TF_B0TT0M: 
hPtr = hPtrRightTop; 
break; 

default: 
hPtr = 0; 

} 

if (hPtr) 

WinSetPointer (HWND_DESKTOP, hPtr); 
else 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
break; 

default: 

mReturn = (*pfnFrameProc) (hWnd, msg, mpl, mp2); 
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break; 

} 

return (mReturn); 

} 

MRESULT EXPENTRY MenuSubclassProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

if (msg == WM_CONTROLPOINTER) 
return ((MRESULT)hPtrPopupMenu); 
else 

return (*pfnMenuProc) (hWnd, msg, mpl, mp2); 


MRESULT EXPENTRY SysMenuSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

if (msg == WM_CONTROLPOINTER) 
return ((MRESULT)hPtrPopupMenu); 
else 

return (*pfnSysMenuProc) (hWnd, msg, mpl, mp2); 


MRESULT EXPENTRY TitleBarSubclassProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

MRESULT mReturn = 0L; 

ULONG ulCurState, 
ulNewState; 

HPS hps; 

switch (msg) 

{ 

case WM_MOUSEMOVE: 

WinSetPointer (HWND_DESKTOP, hPtrTitleBar); 
break; 

case TBM_QUERYHILITE: 

mReturn =(MRESULT)(WinQueryWindowULong(hWnd,QWLJJSER) & 0x0001); 
break; 

case TBM_SETHILITE: 

mReturn = (MRESULT)TRUE; 

ulCurState = ulNewState = WinQueryWindowULong (hWnd,QWL_USER); 
if (LOUSHORT(mpl)) 
ulNewState J = 1; 
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else 

ulNewState &= ~1; 

/* Only need to update if the state is changing */ 
if (ulCurState == ulNewState) 
break; 

WinSetWindowULong (hWnd,QWL_USER, ulNewState); 

hps = WinGetPS (hWnd); 

PaintTitleBar (hWnd,hps); 

WinReleasePS (hps); 
break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

PaintTitleBar (hWnd,hps); 

WinEndPaint (hps); 
break; 

default: 

mReturn = (*pfnTitleBarProc) (hWnd, msg, mpl, mp2); 
break; 


return (mReturn); 

} 


MINIMDLH 


/* 


MiniMDI Header File 
Chapter 3 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define 

ID APPNAME 

1 

#define 

IDD_TOOLBAR 

2 

#define 

IDDJVININFO 

3 

#define 

ID_CHILDWINDOW 

11 

#define 

IDPTR_HEART 

20 

#define 

IDPTR_CLIENT 

21 

#define 

IDPTR SYSMENU 

22 
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#define 

IDPTRJV1ENU 

23 

#define 

IDPTRJVIINMAX 

24 

#define 

IDPTR_LEFT 

25 

#define 

IDPTR_T0P 

26 

#define 

IDPTR_LEFTTOP 

27 

#define 

IDPTR_RIGHTTOP 

28 

#define 

IDPTR_TITLEBAR 

29 

#define 

IDPTR_POPUPMENU 

30 

#define 

IDM_WINDOW 

100 

#define 

IDM_NEWCHILD 

101 

#define 

IDM_NEXTCHILD 

102 

#define 

IDM_CLOSEALL 

103 

#define 

IDM_ABOUT 

104 

#define 

IDM_ARRANGEMENU 

110 

#define 

IDM_TILE 

111 

#define 

IDM_CASCADE 

112 

#define 

IDM_ARRANGE 

113 

#define 

IDC_WININFO 

200 

#define 

IDC RED 

201 

#define 

IDC_GREEN 

202 

#define 

IDC_BLUE 

203 

#define 

IDC_M0VE 

204 

#define 

IDC_TRACK 

205 

#define 

IDC_OPEN 

206 

#define 

IDC_TITLE 

300 

#define 

IDC_XP0S 

301 

#define 

IDC_YP0S 

302 

#define 

IDC_WIDTH 

303 

#define 

IDC_HEIGHT 

304 

#define 

IDC STATE 

305 


MINIMDI.DEF 


MINIMDI WINDOWAPI 
'MiniMDI Program (c) 


NAME 

DESCRIPTION 

PROTMODE 

HEAPSIZE 

STACKSIZE 

EXPORTS 


4096 

32768 

ClientWndProc 


ChildWndProc 


ToolBarDlgProc 

WinlnfoDlgProc 

FrameSubclassProc 


Blain, 


Delimon, & English, 


1993 
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TitleBarSubclassProc 

SysMenuSubclassProc 

MenuSubclassProc 

ChildSubclassProc 

AboutDlgProc 


How MINIMDI Works 

This application will do several things. The main window will have all its frame controls 
subclassed as well as the frame window itself. This will enable you to set the pointer to 
various pointer shapes as the mouse is moved over the various frame control windows. In 
addition, the frame window of a child window may be subclassed if the Move option is 
disabled or the Track option is enabled. To perform the subclassing, you define a sub¬ 
class window function for each window class: 


/* Window Subclass Functions */ 

MRESULT EXPENTRY ChildSubclassProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY FrameSubclassProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY MenuSubclassProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY SysMenuSubclassProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY TitleBarSubclassProc (HWND,ULONG,MPARAM,MPARAM); 

We are using two application-defined messages: 

#define WM_USER_POSITION WMJJSER+1 

#define WM_USER_CHILDACTIVATE WMJJSER+2 

WM_USER_POSITION is a message we will post to the toolbar dialog window after it is 
created. The WM_USER_CHILDACTIVATE message will be posted to the toolbar dialog when 
a child window becomes active. 


In addition, each child window will use application-defined window data: 


/* User-Defined Window Extra Words */ 

#define QWL_C0L0R_RGB QWLJJSER 

#define QWL_MOVE QWL_COLOR_RGB + sizeof(ULONG) 

#define QWL_TRACKING QWL_MOVE + sizeof(BOOL) 

#define QWL_0PEN QWL_TRACKING + sizeof(BOOL) 

#define QWL EXTRA QWL_0PEN + sizeof(BOOL) 


/* ULONG */ 
/* BOOL */ 
/* BOOL */ 
/* BOOL */ 


The offset of each item will be identified by an application-defined QWL_ definition. 
Each offset is defined in reference to the previous offset plus the size of the previous data 
item. The total number of bytes that must be allocated for each window of the child class 
is QWL_EXTRA, which is the sum of all the items. 
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Processing begins by creating the main application window and then subclassing all 
the frame control windows except the FID_MINMAX frame control: 

/* Create the main application window */ 
hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0L, 

&flFrameFlags, szClientClass, szTitle, 0, NULL, ID_APPNAME, 
&hWndClient); 

/* Subclass the frame control windows */ 

pfnFrameProc = WinSubclassWindow (hWndFrame, FrameSubclassProc); 
pfnTitleBarProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_TITLEBAR), TitleBarSubclassProc); 
pfnSysMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_SYSMENU), SysMenuSubclassProc); 
pfnMenuProc = WinSubclassWindow ( 

WinWindowFromID (hWndFrame, FID_MENU), MenuSubclassProc); 

InitializeAppWindow (hWndClient); 

WinShowWindow (hWndFrame, TRUE); 

The main window is created with the WS_VISIBLE flag turned off. This enables you 
to complete the initialization and create the child windows before any painting is done. 
The call to InitializeAppWindow takes care of initialization: 

VOID InitializeAppWindow (HWND hWnd) 

{ 

WinRegisterClass (hab, "CHILD", ChildWndProc, 0, QWL_EXTRA); 

hWndToolBar = WinLoadDlg (HWND_DESKTOP, hWnd, ToolBarDlgProc, 

0L, IDD_TOOLBAR, NULL); 

/* Create three children initially */ 

CreateChildWindow (hWnd); 

CreateChildWindow (hWnd); 

CreateChildWindow (hWnd); 

WinPostMsg (hWndToolBar, WM_USER_POSITION, 0L, 0L); 

WinPostMsg (hWnd, WM_COMMAND, (MPARAM)IDM_TILE, 0L); 
return; 


The registration of the child window class "CHILD" specifies that QWL_EXTRA bytes 
are to be allocated for window data. The toolbar dialog window is loaded with a call to 
WinLoadDlg. This creates a modeless dialog window that uses the dialog template iden¬ 
tified by IDD_T00LBAR. Because you want the dialog to be capable of moving freely about 
the screen without restriction to the boundary of the application window, you use a 
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parent of HWND_DESKTOP. The main application window will serve as the owner window 
for the dialog. You arbitrarily create three child windows to begin the application. Next, 
post the WM_USER_POSITION message to hWndToolBar. Because you have not entered the 
WinGetMsg loop, the WM_SIZE message for the main application window has not been 
retrieved from the message queue. You want to position the toolbar initially at the lower- 
left corner of the application window; however, because the application window has not 
been sized yet, you post this message so that it is retrieved and processed after the WM_SIZE 
message. You then post aWM_COMMAND message with the command identifier of IDM_TILE 
so that the three child windows will be arranged in a tiled manner. 

The Arrangelcons function is used to neatly arrange the minimized child windows 
at the bottom of the client window. You will use the WinSetMultWindowPos to make a 
single call to arrange all the minimized windows. Here, you use the window enumera¬ 
tion functions to retrieve the child windows one at a time in Z-order from top to bot¬ 
tom. A call to IsWindowMinimized will tell whether the window is an iconic window; if 
so, you fill in the SWP structure for the current minimized window. Here is where you 
need to perform a little PM trick: 

if ( IsWindowMinimized (hWndChild) ) 

{ 

pSwp[ulChildCnt].fl = SWP_MOVE j SWP_FOCUSDEACTIVATE; 

pSwp[ulChildCnt].x 

pSwp[ulChildCnt].y = 0; 

pSwp[ulChildCnt++].hwnd = hWndChild; 

/* Destroy the current minimize position -- a little 
PM trick */ 

WinSetWindowUShort (hWndChild,QWS_XMINIMIZE,(USHORT)-1); 
WinSetWindowUShort (hWndChild,QWS_YMINIMIZE,(USHORT)-1); 

} 

Every frame window has the X and Y position from its last minimization in its win¬ 
dow data. These values are referenced with the WinQueryWindowUShort function and 
the QWS_XMINIMIZE and QWS_YMINIMIZE offsets. When a window is minimized, PM will 
try to calculate a position for the icon. OS/2 will skip positions that are currently in use 
by another iconic window. OS/2 does this by examining the QWS_XMINIMIZE and 
QWS_YMINIMIZE values of all sibling windows. Because we are rearranging the icons, we 
don’t want an iconic window to have an existing position because OS/2 will skip that 
position. Setting these values to -1 indicates to PM that the icon has no previous mini¬ 
mized position. When WinSetMultWindowPos is called and an iconic window has the 
SWP_MOVE flag set, PM will arrange each icon in order along the bottom of the window 
(see Figure 3.13). This eliminates the need to come up with any algorithm for spacing 
and positioning iconic windows. 
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Figure 3.13. 
Diagram of iconic 
windows neatly 
arranged. 
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The CascadeChildWindows function is used to arrange the nonminimized windows 
in a cascaded fashion (see Figure 3.14). 


Figure 3.14. 

Diagram of windows 
arranged in a cascaded 
fashion. 
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Here, you want to enumerate the child windows in reverse Z-order (from bottom to 
top). You can’t use the window enumeration functions because that returns windows in 
Z-order from top to bottom. You can, however, do your own enumeration by querying 
the extreme bottom child window 

hWndChild = WinQueryWindow (hWnd, QW_B0TT0M); 

and by repeatedly querying the previous child window 

hWndChild = WinQueryWindow (hWndChild, QW_PREV); 
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until no more children exist. Here is where it gets a little tricky with iconic windows. 
When a frame window is minimized, a window of class WC_I CONTEXT is created to con¬ 
tain the text displayed below the icon. This WC_ICONTEXT window will enumerate as one 
of the child windows. PM helpfully assigns all WC_ICONTEXT windows an identifier of 
zero. As long as you don’t use an identifier of zero for your child windows, you can query 
the identifier of the window and skip those that are zero: 

while (hWndChild) 

{ 

/* Skip ICONTEXT windows and minimized windows */ 
if ( WinQueryWindowllShort (hWndChild, QWS_ID) && 

!IsWindowMinimized (hWndChild) ) 

{ 

GetNextWindowPos (ulChildCnt, &pSwp[ulChildCntj); 
pSwp[ulChildCnt].fl = SWP_M0VE | SWP_SIZE | SWP_SH0W; 

/* If child is maximized then restore it */ 
if (IsWindowMaximized (hWndChild)) 

pSwp[UlChildCnt].fl |= SWP_RESTORE; 

pSwp[ulChildCnt++].hwnd = hWndChild; 

} 

/* Query the previous child frame window in the z-order */ 
hWndChild = WinQueryWindow (hWndChild, QW_PREV); 

} 


For each noniconic, non-WC_ICONTEXT window, you call GetNextWindowPos to cal¬ 
culate the size and position for the next cascaded window. If the child window is cur¬ 
rently maximized, you add the SWP_RESTORE flag so that the maximized child is restored 
in addition to being resized and positioned. 

The CloseAllChildWindows function merely enumerates all the child windows and 
calls WinDestroyWindow to remove the window. 

CreateChildWindow is called to create a new child window. Each child window is 
created with a titlebar, system menu, sizing border, minmax menu, and icon: 

ULONG fIChildFrameFlags = FCF_TITLEBAR j FCF_SYSMENU | FCF_SIZEBORDER 

FCF_MINMAX | FCF_ICON \ FCF_NOBYTEALIGN; 

if (hWndChildFrame = WinCreateStdWindow (hWnd, 0L, &fIChildFrameFlags, 
"CHILD", "", 0L, 0L, ID_CHILDWINDOW, &hWndChild)) 

When we create a new child, we want it to be the active window. If the current active 
window is maximized, we must first restore it: 
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if (hWndActiveChild && IsWindowMaximized (hWndActiveChild)) 

WinSetWindowPos (WinQueryWindow (hWndActiveChild, QW_PARENT), 

0L, 0L, 0L, 0L, 0L, SWP_RESTORE); 

Because the client window made with WinCreateStdWindow creates the client win¬ 
dow with no owner, you assign the owner of the client to be the frame: 

WinSetOwner (hWndChild, hWndChildFrame); 

The initial position of a newly created child window will be the next available cas¬ 
caded window position: 

GetNextWindowPos (ulNumChildren - 1 L, &Swp); 

WinSetWindowPos (hWndChildFrame, 0 L, Swp.x, Swp.y, Swp.cx, Swp.cy, 
SWP_MOVE | SWP_SIZE | SWP_SHOW j SWP_ACTIVATE); 

You are also keeping track of the number of child windows with a heart in the titlebar. 
Because a new child was just created, you force the titlebar to repaint. This can be done 
by invalidating the titlebar window: 

WinlnvalidateRect (WinWindowFromID(hWndFrame,FID_TITLEBAR), 

NULL, FALSE); 

The IsWindowMaximized and IsWindowMinimized functions check the window style 
of the frame window for the WS_MAXIMIZED or WS_MINIMIZED flag. It is necessary to query 
the style of a frame window because client windows do not use those flags. Because you 
are always passing the handle of either the child’s frame window or the child’s client 
window, you can just check whether the identifier is FID_CLIENT. If so, query the parent 
window and use it: 

if (WinQueryWindowUShort (hWnd, QWS_ID) == FID_CLIENT) 
hWnd = WinQueryWindow (hWnd, QW_PARENT); 

SwitchToNextChildWindow will locate the next child below the currently active child 
window and move it to the top of the Z-order while moving the currently active child 
window to the bottom of the Z-order. To get the next child below the currently active 
child, you use QW_NEXT on the frame window of the active child. 

while ( (hWndNext = WinQueryWindow (hWndNext, QW_NEXT)) && 

!WinQueryWindowUShort (hWndNext, QWS_ID)) 

{ 

> 

As mentioned earlier, be sure you don’t attempt to use a WC_I CONTEXT window. When 
the next window is found, two calls to WinSetWindow change the Z-order of your win¬ 
dows. This ensures that if the active child window is maximized, it is restored as well: 

WinSetWindowPos (hWndNext, HWND_T0P, 0 , 0 , 0 , 0 , 

SWP_ZORDER | SWP_ACTIVATE); 
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WinSetWindowPos (hWndActiveFrame, HWNDJ30TT0M, 0, 0, 0, 0, 

IsWindowMaximized (hWndActiveFrame) ? SWP_RESTORE ] SWP_ZORDER : 

SWP_ZORDER); 

TileChildWindows is used to arrange the nonminimized child windows in a tiled 
fashion (see Figure 3.15). 


Figure 3.15. 
Diagram, of windows 
arranged in a tiled 
fashion. 
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The algorithm will arrange the child windows, moving from the upper-left corner to 
the right and attempting to have as many windows the same size as possible. Here, you 
enumerate the child windows in Z-order from top to bottom, again skipping WC_ICONTEXT 
and minimized windows. If the child window is currently maximized, add in the 
SWP_RESTORE flag so that the maximized child is restored. For both cascading and tiling, 
be sure that the icon windows are not covered by the non-icon windows. 

if (ulNumMinChildren) 

Recti.yBottom += WinQuerySysValue (HWND_DESKTOP, SV_CYIC0N) * 2; 

The bottom of the client rectangle used for calculations is shifted up to leave room 
for the icons if any minimized children exist. 
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Introduction to Common Dialogs 

The common dialogs greatly simplify the amount of work a programmer must do to 
perform a number of routine tasks. These dialogs provide the functionality for tasks most 
programs need to perform at one time or another, such as opening and saving files or 
selecting fonts. 

In the past, every application development team was forced to write 
code to perform routine tasks, tasks that practically every appli¬ 
cation needed to perform. To make application development 
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easier, PM provides dialogs that programmers may use in their code to perform these 
routine operations. Using these common dialogs in your application achieves more than 
relieving some of the coding burden. They provide a consistent interface for the user. 
Not only will your applications be consistent with each other, but also applications will 
be consistent even among programmers and unrelated applications if they use these 
common dialogs. 

Practice with the CONTROL Sample Application 

The concepts in this chapter will be far more intelligible if you have some hands-on ex¬ 
perience with the common file dialogs. Open the control application that was installed 
from the distribution disk for Real-World Programming for OS/2 2.1. Use of the menu 
choices in this sample application should be fairly self-explanatory to anyone accustomed 
to a menu-windowing interface. You do not need to worry about backing up files, as you 
would normally, because the SaveAs choice in the application has been deliberately left 
unworking. Spend some time familiarizing yourself with the use of these controls. 

The CONTROL sample application has two major parts. One demonstrates the 
common file API, and the other demonstrates the common font API. These are divided 
between the File and Font choices on the menu bar. 

The File Menu 

The File menu contains those menu choices that concern the common file dialogs. When 
you start the application and click the File menu choice, the application appears as illus¬ 
trated in Figure 4.1. 

Basic Open 

The Basic Open menu choice, shown in Figure 4.2, displays the basic dialog box for 
enabling the user to choose a file to open. The file, however, is not read, and no data is 
written to the client area. 

Open And Display 

Open And Display enables the user to open any file for display in the client area. The 
client area processing is, however, only set up to display text files, so only these will ap¬ 
pear in an intelligible form. Only the first few lines of text from the file are all that are 
displayed in the client area. No editing capabilities are provided. 
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Figure 4.1. 

Open and Save As 
menu. 
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Figure 4.2. 

Basic File Open dialog. 
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Custom Open Template 

The Custom Open Template, shown in Figure 4.3, operates similarly to the Open And 
Display menu choice, with one important addition. Notice the check box for Save Di¬ 
rectory. Try changing the file path to some directory other than that displayed when the 
application opens, open a file, then select Custom Open Template from the menu again. 
Notice that the dialog has returned to the directory that you chose earlier. 


Figure 4.3. 

File Open dialog using a 
custom template. 



Save As 

The Save As option is included merely to show the workings of this common file dialog. 
No code for actually saving the files is included. 


The Font Menu 

The Font menu contains those choices that pertain to the common font dialogs. These 
are shown in Figure 4.4. 

The Basic Font menu choice causes the Basic Font dialog to be displayed, as shown 
in Figure 4.5. The choices in the dialog should be fairly self-explanatory. 
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The Reset button under Change Font sets the font selection back to what it was be¬ 
fore you began changing it. Notice also that changes are not made to the displayed text 
until you select Ok. Because Change Font, shown in Figure 4.6, is a modal dialog, this is 
the expected behavior. The user cannot continue the process until either Ok or Cancel is 
selected in this dialog. 


Figure 4.6. 

Change Font dialog. 
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Modeless Change Font 

The Modeless Change Font menu choice is similar to that of Change Font; however, it 
is a modeless. This means that the user may proceed with other processing in the appli¬ 
cation without selecting Ok or Cancel. In fact, the Modeless Change Font dialog will 
remain open even if the user chooses to open another file. 

Notice the Direct Update check box (see Figure 4.7). This will cause the font changes 
to be applied immediately to the displayed text. Otherwise, font changes may be applied 
to the displayed text by clicking the Apply button. 

Development of the Sample 

For both the common file and font dialogs, this sample application demonstrates 
more than a single scenario of their use. Several different ways of presenting the file and 
font data occur under each of the menu choices. Although each of the examples of using 
the common file dialogs has been combined in a single application, each is written 
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somewhat independent of the previous samples. There will be, therefore, some redun¬ 
dant storage of data between calls to the dialog. 


Figure 4. 7 . 

The Modeless Change 
Font dialog box. 




File Dialog 

The common file dialog is a set of functions and resources or dialog templates provided 
within PM. These provide list boxes and combination boxes that allow directories to be 
navigated and files to be selected. Only a function call is needed to bring up a dialog box 
that would be far more complex to code individually. An edit window is also provided to 
enter a full path and filename or a wildcard file spec. This is certainly a welcome feature, 
because it prevents the necessity of coding an activity that is common to most applica¬ 
tions. A file may be selected by double-clicking the filename in the files list box or push¬ 
ing the Ok button. The dialog may be closed by pushing the Cancel button or by using 
the escape key. 

The common file dialog has three API entries. These are as follows: 

WinFileDlg Creates and displays the File Open or Save As 

dialog and returns the user’s selection(s). 

WinDefFileDlgProc Default dialog procedure for the File Open or 

“Save As” dialogs. 

WinFreeFileDlgList Frees the memory allocated when the 

FDS_MULTIPLESEL flag is set in the fl field of 
the FILEDLG structure. 
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Let’s take a closer look at the WinFileDlg function: 

WinFileDlg(hwndParent,hwndOwner,pFileDlg); 

HWND hwndParent Window handle of the parent window of the 

created dialog box. The parent window may 
be HWND_DESKTOP or a valid window 
handle. 

HWND hwndOwner Window handle of the requested owner. PM 

will select the actual owner by searching up 
the parent chain beginning with 
hwndOwner. The first window that is a child 
of hwndParent will be set as the dialog box 
owner. If no children of hwndParent are 
found, the owner is set to NULL. 

PFILEDLG pFiledlg Pointer to a FILEDLG structure. The 

contents of the pFiledlg structure define the 
appearance, location, and behavior of the 
Open or Save As dialog. 

Creating a Simple Application 

We wrote the code in this book to make it easier to cannibalize. If you are adventurous, 
creating a basic file selection dialog in your application is not difficult. By adding a menu 
and four lines of code to the skeleton program from Chapter 2, “OS/2 Application Win¬ 
dow Fundamentals,” you can quickly create an application that displays a modal file se¬ 
lection dialog. Remember to declare the necessary file dialog structure, too. 

First, initialize all fields of the FILEDLG structure to NULL. Then, set the required cbSize 
and f 1 fields in the structure. The flags indicate that an open dialog should be created 
and centered relative to its owner window: 

memset(&FileDlg,0,sizeof(FILEDLG)); 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.fi = FDS_CENTER | FDS_OPEN_DIALOG; 

WinFileDlg(HWND_DESKTOP,hWndFrame,(PFILEDLG)&FileDlg); 
if (FileDlg.IReturn == DID_0K) 

WinSetWindowText(hWndFrame,(PSZ)FileDlg.szFullFile); 

The WinFileDlg function returns TRUE if the dialog was successfully created and FALSE 
if an error occurs. Modal dialogs are created by default. Modal dialogs are those that will 
not return to the caller until the dialog has been dismissed. Dismissing a dialog is an¬ 
other way to describe terminating or closing a dialog. The term originates from the PM 
function WinDismissDlg that is used to destroy dialogs. The FILEDLG structure not only 


132 



Chapter t: 2.1 Common Dialogs 


defines the type and location of the dialog, but also contains selections made in the dia¬ 
log. The default file open dialog may be ended with either the Ok or Cancel pushbuttons 
The IReturn field will indicate which control dismissed the dialog. If Ok was selected, 
theszFullFile name will contain the full pathname of the selected file. If Cancel was 
chosen, the szFullFile parameter is undefined. In the previous sample, the filename 
will be set as the titlebar text if Ok was selected. 


The FILED LG Structure 

The FILEDLG structure contains many more fields than the two used in the previous 
example. To fully understand the ways the File Open dialog may be used, the FILEDLG 
structure must be examined. We will examine these before moving on to a more com¬ 
plex example. The FILEDLG structure is defined as follows: 

ULONG cbSize Structure size in bytes. 

ULONG fl Flags that define the dialog appearance, 

location, and behavior. 


One of the following must be specified: 

FDS_OPEN_DIALOG Creates the Open dialog. 

FDS_SAVEAS_DIALOG Creates the Save As dialog. 

Zero or more of the following may be added: 


FDS_APPLYBUTTON 


FDS_CENTER 

FDS_CUSTOM 


FDS_HELPBUTTON 


The Apply button is added to the dialog 
between the Ok and Cancel buttons. This 
button should be used on modeless dialogs. 
You must supply your own dialog procedure 
to process this control’s command messages. 
Centers dialog relative to owner window. 
This flag will override a dialog position 
specified by the X and Y parameters. 

Creates the dialog using the custom dialog 
template found in hMod with ID usDlgld. 
You must still supply the Open or Save As 
dialog type flag so that WinFileDlg knows 
how to process the control windows. 

The help button is added to the dialog. 
When the button is clicked, a WM_HELP 
message is sent to the owner window. If the 
owner is a frame window, it must be 
subclassed to receive the WM_HELP 
message. 
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FDS_MODELESS 


FDS_PRELOAD_VOLINFO 


FDS_INCLUDE_EAS 

FDS_MULTIPLESEL 


FDS_ENABLEFILELB 


FDS_FILTERUNION 


ULONG ulUser 

LONG IReturn 


LONG 1SRC 


The dialog is created modeless; the default is 
to create a modal dialog. When this flag is 
used, WinFileDlg returns the window handle 
of the created dialog. 

This option queries the volume label for all 
drives before displaying the dialog. The 
values are placed in the drives combination 
box after the drive letter. If this flag is not 
specified, the volume label is displayed in the 
combo box when the directory is selected. 
Because all drives including removable are 
queried, using this option can increase 
significantly the time required to display the 
dialog. 

Always Loads LA information. 

Allows multiple selections in the file list box. 
Selected strings are returned through the 
papszFQFilename parameter. 

When the FDS_SAVEAS_DLALOG is 
specified, the file list box is disabled. Using 
this will enable the file list box. 

The default behavior is to display those files 
that are the intersection of the file type and 
extended attribute filters. Use this flag to 
display the union of those filters. 

Unused field reserved for application use. 
WinDefFileDlgProc will set this value to 
the ID of the control that resulted in the 
dismissal of the dialog. It is not the result 
value passed to the WinDismissDlg func¬ 
tion. If your custom dialog callback calls 
WinDismissDlg, it must still set the 
ulReturn field to the desired control ID. 

If the WinFileDlg function fails, this field 
will contain one of the following errors 
codes: 


FDS_ERR_DEALLOCATE_MEMORY 

FDS_ERR_FILTER_TRUNC 

FDS_ERR_INVALID_DIALOG 

FDS_ERR_INVALID_DRIVE 

FDS_ERR_INVALID_FILTER 
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FDS_ERR_INVALID_PATHFILE 

fds_err_out_of_memory 

FDS_ERR_PATH_T 00_L0NG 

FDS_ERR_TOO_MANY_FILE_TYPES 

FDS_ERR_INVALID_VERSION 

FDSJERR_INVALID_CUSTOMJHANDLE 

FDS_ERR_DIALOG_LOAD_ERROR 

FDS_ERR_DRIVE_ERROR 


PS 

pszTitle 

Pointer to a null-terminated string that is 
placed in the titlebar of the dialog. If this 
parameter is NULL, the default title for the 
open dialog is “Open” and “Save As” for the 
save dialog. 

PSZ 

pszOKButton 

Pointer to a null-terminated string that 
contains the text to be placed in the Ok 
pushbutton. The default string is “Ok.” 

PFNWP 

pfnDlgProc 

Application-supplied dialog procedure that 
will be called in place of 
WinDefFileDlgProc. 

PSZ 

pszIType 

Extended-attribute type filter. 

PAPSZ 

papszITypeList 

Pointer to an array of pointers that point to 
null-terminated file type strings. The end of 
the array is marked with a NULL pointer. 

PSZ 

pszl Drive 

Pointer to a null-terminated string that 
contains the initial drive to display in the 
drives combo box. It must be a drive letter 
followed by a semicolon, for example, C:. If 
the drive provided is not valid, the first entry 
in the drives combo box is selected as the 
default drive. If this parameter is NULL, the 
current drive is used. 

PAPSZ 

papszIDriveList 

Pointer to an array of pointers to null- 


terminated drive strings to be added to the 
drop-down list of logical drives. If this 
parameter is NULL, all available drives are 
displayed. 

HMODULE hMod If the FDS_CUSTOM flag is set, 

WinFileDlg will attempt to load a dialog 
resource with the ID specified in the usDlgld 
field from this module. If hMod is NULL, 
the current executable is searched. 
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CHAR szFullFile Character array of CCHMAXPATH bytes. 

Before the call to WinFileDlg, this array may 
be initialized with the initial filename to 
display in the dialog. Wildcards may be used. 

PAPSZ papszFQFilename Pointer to an array of pointers that point to 

null-terminated filename strings. There will 
be one entry for each file selected in the file 
list box. The number of entries in the array 
is indicated by the ulFQFCount parameter. 
The FDS_MULTIPLESEL flag must be used 
to allow multiple files to be selected. This 
memory should be freed by calling the 
WinFreeFileDlgList function. 


ULONG 

ulFQFCount 

The number of pointers in the array pointed 
to by the papszFQFilename parameter. 

USHORT 

usDlgld 

If the FDS.CUSTOM flag is set, 
WinFileDlg will attempt to load a dialog 
resource with this ID from the module 
specified in the hMod field. 

SHORT 

X 

Screen X dialog coordinate, which is ignored 
if the FDS_CENTER flag is used. 

SHORT 

y 

Screen Y dialog coordinate, which is ignored 
if the FDS_CENTER flag is used. 

SHORT 

sEAType 

Selected extended-attribute type. 


Using Nondefault Values 

Let’s take advantage of the features the dialog offers. First, let’s provide a title string for 
the dialog. It will indicate which application is displaying the dialog. To do this, we call 
the set_title function, which will load the application name string from the resource 
file and concatenate a hyphen followed by the name of the dialog. The dialog name is 
dependent on the string ID passed as the second parameter to the set_title function. 
This string is then set as the title in the pszTitle parameter. 

Rather than setting the filename in the titlebar, we read the selected file and display 
it in the client area. If IReturn is set to DID_0K when the dialog returns, the load_f ile 
function is called. It will open the file and read it into an allocated memory block pointed 
to by pFileText. If an error occurs during the loading process, a message box is posted. 
The filename is then copied to the szFilePath character array, and the client area is in¬ 
validated. Because we are primarily interested in displaying ASCII text files, we will set 
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the initial file spec in the FILEDLG structure. The szFullFile that will return a selected 
filename can also be used to supply an initial file or wildcard search pattern. The IDS_PATH 
resource string (“*.TXT”) is loaded into the szFullFile parameter. The function call to 
do this is as follows: 

WinLoadString (hab,NULL,IDS_PATH,CCHMAXPATH,(PSZ)&FileDlg.szFullFile) ; 

Rather than allowing all drives to be displayed, we will use the papszIDriveList 
parameter to display only the nonremovable drives available to the system. 

This parameter points to an array of pointers to null-terminated strings that identify 
the drive letter to be added to the drives combo box. The string should include the drive 
letter followed by a colon. When the program starts, the get_fixed_d rives function is 
called to initialize the pD rives List variable. The drives type is queried by calling the 
DosQueryFSAttach function and requesting information level 1. The iType field of the 
returned buffer will indicate whether the drive is local or remote. After the drive is identified 
as local, the device is opened and queried by using the DosDevIOCtl fountain. If a drive 
is determined to be fixed, it is added to the pDrivesList pointer array. Before the file 
open dialog is posted, the papszIDDrivelist parameter is set to pDrivesList: 

FileDlg.papszIDriveList = pDrivesList; 

Now that the file is loaded, we need code that will display the text in the client win¬ 
dow. For this, we will use the WinDrawText function. Data will be read from the file and 
output to the window formatted as a line of text within a supplied rectangle. Essentially, 
we are dividing the client window into a group of rectangles, stacked one on top of the 
other. Each line of text will be drawn into a rectangle. To position the text correctly, we 
must know the client window size and the height of the font being used. The client win¬ 
dow size is updated in the static Recti variable when the WM__SIZE message is received. 
The new width and height of the window is passed in the high and low words of the mp2 
parameter: 

case WM_SIZE: 

Recti.xLeft = Recti.yBottom = 0; 

Recti.xRight = SH0RT1FROMMP(mp2); 

Recti.yTop = SH0RT2FR0MMP(mp2); 
break; 

The height of the current font is queried by calling GpiQueryFontMetrics with the 
Presentation Space handle returned from WinBeginPaint. In this example, we will cal¬ 
culate line spacing by adding IMaxBaselineExt and lExternalLeading. This is per¬ 
formed with the following function calls: 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 

(PFONTMETRICS)&FontMetrics); 

cyHeight = FontMetrics.IMaxBaselineExt + FontMetrics.lExternalLeading; 
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Now that we have the client size and font height, the text can be output by calling 
WinDrawText and advancing the current position based on the number of characters 
drawn. After the end of the text is reached or the client area has been filled with text, the 
loop is exited: 

lHeight = Recti.yTop; 
for ( iTotalDrawn = 0; 

(iTotalDrawn < ulTextSize) && (Recti.yTop > 0); 

Recti.yTop -= cyHeight) 

{ 

iDrawn = WinDrawText(hPS, 

min (0x1000,(ulTextSize - iTotalDrawn)), 
pFileText + iTotalDrawn, 

(PRECTL)&Rectl,CLR_BLACK,CLR_WHITE, 

DT_LEFT | DT_TOP | DT_WORDBREAK); 
if (iDrawn) 

iTotalDrawn += iDrawn; 

else 

iTotalDrawn++; 

} 

Recti.yTop = lHeight; 

To ensure visibility for the text displayed, the client window is registered with the 
CS_SIZEREDRAW style flag. This will cause the entire client window to be invalidated 
whenever the window is resized. The text will then be output based on the new client 
size. Now that our sample application is capable of opening and displaying files, let’s add 
our custom dialog template. 


Custom Template 

It is possible to create your own File Open or Save dialog template and still have the 
WinDef FileDlgProc do all the processing for you. Some guidelines, though, must be 
followed. The custom template must contain all the controls of the default dialog. Con¬ 
trol windows must be the same style and ID of those in the default dialog template. 
Controls that are not needed should be hidden. The window ID range 0x000 to OxFFF 
is reserved for the default control ID. To avoid any conflict, user defined additions should 
use ID values of 0x1000 (WM_USER) and greater. 

Using the PM dialog editor, a custom open dialog is created. All the basic controls 
found in the standard dialog are present, but in a different order. In addition to the basic 
controls, a new check box button is added. This check box enables the user to specify 
whether the current directory should be retained. The current path and filename are saved 
as an atom in the variable atSavePath. (Atoms are PM features in which unique strings 
are assigned numeric identifiers. This saves space and allows the identifiers to be manipu¬ 
lated more easily than strings.) 
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Creating the custom file open dialog requires some additional parameters to be set. 
The FDS_CUSTOM flag is added to the f 1 field, and the usDlgld parameter is set to the ID 
assigned to the custom dialog. Notice that although we are providing a dialog template, 
FDS_0PEN_DIAL0G or FDS_SAVEAS_DIALOG must still be specified. Without one of these 
flags, the dialog creation will fail. The hMod field must also be set to indicate where to 
search for the resources. Because the new dialog resource will be bound into the execut¬ 
able, the module handle may set to NULL. A NULL module handle will cause WinFileDlg 
to search the current module for the requested resource. 

WinFileDlg handles the processing for all the standard control windows. If your 
custom dialog template does not define additional controls, WinDef FileDlgProc can be 
used to process the dialog. Processing for any user-supplied controls, however, must be 
done in a user-supplied dialog procedure. To do that, thepfnDlgProc parameter of the 
FILEDLG structure is set to our private dialog procedure, FileOpenDlgProc. Providing a 
private callback subclasses the file open dialog. Anytime a window is subclassed, the pre¬ 
vious callback, in this case WinDef FileDlgProc, should be called with all messages re¬ 
ceived. The callback must also be added to the EXPORTS section of the module definition 
file. With the exception of the function name, the callback function must be defined as 
follows: 

MRESULT EXPENTRY FileOpenDlgProc(HWND,ULONG,MPARAM,MPARAM); 

The FileOpenDlgProc dialog callback only processes two messages, WM_INITDLG and 
WM_COMMAND. During the processing of the WM_INITDLG message, the initial state of the 
directory check box must be set. The common dialogs, unlike those created by calling 
WinDlgBox, do not pass a pointer to initialization data in the mp2 parameter of the 
WM_INITDLG message. Data, however, may be shared between the caller and the dialog 
by using the ulUser field of the FILEDLG structure. How does the dialog get the pointer 
to the FILEDLG structure? The 0WL_USER field of the dialog window contains a pointer 
to this structure that may be retrieved by calling WinQueryWindowUlong. When we have 
this pointer, the ulUser field is checked. If it contains a value, the Save Directory button 
is checked. This field will be initialized prior to the WinFileDlg function call to the atom 
handle of the saved path if one existed. After setting the button state, WinDef FileDlgProc 
is then called to allow any default initialization to occur. This is performed with these 
lines: 

case WM_INITDLG: 

pFileDlg = (PFILEDLG)WinQueryWindowULong(hWndDlg , QWLJJSER); 

if (pFileDlg->ulUser) 

WinCheckButton(hWndDlg,DID_SAVE_DIR,1); 

break; 
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A WM_COMMAND message will be sent to the dialog when Ok or Cancel is selected by 
the user. Part of the default processing by WinDef FileDlgProc for these controls is call¬ 
ing WinDismissDlg and setting the return code in the IReturn field of the FILEDLG struc¬ 
ture. Notice that this field is not set by WinDismissDlg, but by WinDef FileDlgProc. If 
your custom dialog procedure dismisses the dialog, it should also set the return code in 
the FILEDLG structure. During the processing of the WM_COMMAND for the DID_0K control 
ID, WinDef FileDlgProc sets the szFullPath to the selected filename. 

FileOpenDlgProc must return to the caller the state of the Save Directory check box. 
If the button is checked, the ulUser field of the FILEDLG structure will be set to the ID 
of the check box, DID_SAVE_DIR. The IReturn field maybe used as an alternate method 
of returning a value to the caller. Notice that this will work only ifWinDefFileDlgProc 
is called with the WM_COMMAND message first: 

case WM_COMMAND: 

switch (SH0RT1FROMMP(mpl)) 

{ 

case DID_0K: 

case DID_CANCEL: 

if(WinQueryButtonCheckstate(hWndDlg 3 DID_SAVE_DIR)) 

{ 

// Do the default processing 

WinDefFileDlgProc(hWndDlg,ulMessage,mpl,mp2); 

// Get the pointer to the FILEDLG structure 
pFileDlg = (PFILEDLG)WinQueryWindowULong(hWndDlg, 
QWLJJSER); 

pFileDlg->ulUser = DID_SAVE_DIR; 
return (0); 

} 

break; 

} 

break; 

In the second example, the dialog was always created by using the file search spec 
“*.TXT” based on the files in the current directory. To make our custom File Open dia¬ 
log smarter, we added the Save Directory check box. Now that the code exists in our 
dialog callback, to set and get the state of that check box, we must save and restore the 
directory. If, upon the return from the WinFileDlg function, IReturn is set to DID_OK 
and ulUser is set to DID_SAVE_DIR, the previous path atom is destroyed, and the file 
and directory contained in szFullFile are saved as the new path atom. If Cancel is se¬ 
lected, no changes to the current file or Save Directory state are made: 

if (FileDlg.IReturn == DID_OK) 

{ 

if (atSavePath) 

atSavePath = WinDeleteAtom(hAtomTable 3 atSavePath); 
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if (FileDlg.ulUser == DID_SAVE_DIR) 

atSavePath = WinAddAtom(hAtomTable,(PSZ)FileDlg.szFullFile); 
load_file((PSZ)&FileDlg.szFullFile); 

} 

Before we call the WinFileDlg function, the set_path function is called to initialize 
the szFullFile variable. You will recall that this parameter will set an initial file spec for 
the dialog. The set_path function takes two parameters. The first is a pointer to the 
szFullFile variable, and the second is the dialog type being created. If the atSavePath 
atom is non-NULL, the atom text containing the fully qualified pathname is retrieved. If 
the File Open dialog is to be created, the text of the saved path is returned. The default 
file save “*.TXT” is then concatenated at the end of the string. If the Save As dialog is to 
be created, the saved file and path are left unchanged. If atSavePath is NULL, the de¬ 
fault “*.TXT” is used. The ulUser field is then initialized with the atom handle. This 
handle is checked during the processing of the WM_INITDLG message in the 
FileOpenDlgProc function. 

Multiple File Selection 

When the FDS_MULTIPLESEL flag is set in the f 1 field of the FILEDLG structure, the file 
selection list box is created to allow multiple selections. The selections are returned to 
the caller in the papszFQFilename parameter of the FILEDLG structure. The 
papszFQFilename points to an array of pointers that point to null-terminated file names. 
The number of entries will be contained in the ulFQFCount. The memory that these strings 
occupy was allocated by PM in the call to WinFileDlg. An application should make its 
own copy of the filenames and free this memory by calling the WinFreeFileListDlg 
function. The WinFreeFileListDlg takes the papszFQFilename as its only parameter: 

WinFreeFileListDlg(FileDlg.papszFQFilename); 

Save As Dialog 

The Save As dialog uses the same template as the file open dialog. The default behavior 
is to disable the file selection list box. This enables the user to see the files in the current 
directory, but not select them. By disabling the list box, an existing file may not be acci¬ 
dentally selected by double-clicking it. An application should not rely on this alone to 
prevent an existing file from being overwritten, however. The list box may be enabled by 
setting the FDS_ENABLEFILELB flag in the f 1 field. If a file is currently being processed, 
a Save As dialog should preload the szFullFile with the path and file of that file. In this 
sample, the contents of szFilePath are copied to the szFullFile parameter. In a com¬ 
mercial application, the path and file should be saved and retrieved from an atom. This 
was demonstrated in the custom dialog template sample shown previously. 
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Font Dialog 

The common font dialog provides an easy way to enumerate and display the fonts avail¬ 
able for the screen or a print device. This dialog is created and manipulated in much the 
same manner as the file dialog. Before we discuss the common font dialog, however, a 
brief summary of font terminology is necessary. Chapter 7 “Creating and Manipulating 
PM Fonts and Text,” provides a full discussion of all the font topics briefly touched on 
in this chapter. 

Understanding the Basics of Fonts 

A font is a collection of characters that share a common height and appearance. The 
collection can be any size, but most fonts you will work with have 256 characters. The 
height of a font is described in points, which is short for printer points. Each printer point 
is 1/72 inch. Although the height of a font can be described exactly, the appearance of a 
font is more difficult to pin down. Fonts are divided into families based on characteris¬ 
tics of the font. A major determinate of a font family is the presence of serifs. A serif is a 
fine line drawn at the end and perpendicular to the major strokes of a character. It often 
appears as a flaring of the stroke. Fonts without serifs are referred to as sans serif. 
Strokes are the lines used to draw the characters of the font. The width of those strokes 
are also used to classify the font in a family. OS/2 2.1 includes fonts from four families 
by default: 

Serif fonts Sans serif fonts 

Times Helvetica 

Courier 

Symbol 

A font family may be further divided into a single font with a unique facename. The 
characters of that font will be representative of the family to which they belong. Certain 
font attributes can be applied to fonts of any family or face. These attributes do not change 
the basic appearance but do modify the manner in which the characters are displayed. 
For example, most fonts can be made italic or bold. 

Font Representation 

Now that we have some understanding about how fonts are classified, let’s look at how 
they are represented. Font representation falls into two categories: outline and image. The 
characters of an outline font are described in terms of the graphics primitives that draw 
the font. Image font characters, on the other hand, are bitmaps. Both have advantages 
and disadvantages. Outline fonts are continuously scalable and may be displayed in any 
point size without a loss of quality. That quality comes at the expense of speed, however, 
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because each character must be drawn when it is output. Image fonts display faster than 
outline fonts because a bitmap exists for each character in the font. Image fonts may not 
be scaled, however. An image font will require a bitmap for each point size it has avail¬ 
able. 

The Common Font API 

With a little font terminology under our belt, let’s look at the two functions available in 
the common font dialog API: 

WinFontDlg Creates and displays the font selection dialog 

and returns user selections. 

WinDefFontDlgProc Default font dialog procedure that handles all 

the processing of the control windows in the 
dialog. 

The WinFontDlg function takes three parameters. The first two are the same as those for 
the WinFileDlg function, which are the window handles of the parent and owner, respec¬ 
tively. The third parameter is a pointer to a FONTDLG structure. It is this structure that de¬ 
fines the appearance and behavior of the dialog. Although creating the Basic Font selection 
dialog is easy, using it in an application requires some work on the application’s behalf. Taking 
advantage of the features of the font dialog requires an understanding of the FONTDLG struc¬ 
ture. This structure has some of the same fields as the FILEDLG, but many are specific to 
fonts: 


ULONG 

cbSize 

Structure size in bytes. 

HPS 

hpsScreen 

Handle to a screen presentation space from 
which fonts are to be enumerated. If NULL, 
a screen PS will be supplied. 

HPS 

hpsPrinter 

Handle to a printer presentation space from 
which fonts are to be enumerated. 

PSZ 

pszTitle 

Pointer to a null-terminated string that should 
be used as the title of the dialog. The default 
string is “Font.” 

PSZ 

pszPreview 

Pointer to a null-terminated string that should 
be used as the text displayed in the preview font 
window. The default string is “abcdABCD.” 

PSZ 

pszPtSizeList 

Pointer to a null-terminated string that is 
a list of point sizes to be displayed in the drop¬ 
down portion of the size combo box. The sizes 
are separated by spaces and defaults to “8 10 12 
14 18 24.” 
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PFNWP pfnDlgProc 
PSZ pszFamilyname 

FIXED fxPointSize 

ULONG fl 

FNT S_APPLYBUTT ON 

fnts_bitmaponly 

FNTS_CENTER 

FNTS_CUSTOM 

FNTS_FIXEDWIDTHONLY 

FNTS_HELPBUTT ON 


Application-supplied dialog procedure. 
Pointer to a null-terminated string that 
identifies an initial family name to 
display in the font name combo box. 
pszFamilyname is also used to return 
the selected font family name. It is, 
therefore, a required parameter. The 
memory pointed to by pszFamilyname 
should be at least FACESIZE in length. 
Initial point size to display preview 
font. This value is placed in the combo 
box edit field, but is not added to the 
drop-down list. 

Flags that define the dialog appearance, 
location, and behavior. 

The Apply button is added to the 
dialog between Ok and Cancel. This 
button should be used on modeless 
dialogs to make a change take effect 
without closing the dialog. You must 
supply your own dialog procedure to 
process this control’s command 
messages. 

Only enumerate image fonts in the 
dialog box. When this option is 
selected, the Outline check box is 
disabled. 

Centers dialog relative to owner 
window. This flag will override a dialog 
position specified by the X and Y 
parameters. 

Creates the dialog using the custom 
dialog template found in hMod with 
the ID supplied in usDlgld. 

Only enumerate fixed pitch fonts in the 
dialog. A font is fixed pitch if the width 
of all characters is equal. 

A help pushbutton is added to the 
dialog. When the button is pushed, a 
WM_HELP message is sent to the 
owner window. If the owner is a frame 
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FNTSJNITFROMFATTRS 

FNTS_MODELESS 

FNTS_NOSYNTHESIZEDFONTS 

FNTS_OWNERDRAWPREVIEW 

FNTS_PROPORTIONALONLY 

FNTS_RESETBUTTON 

FNTS_VECTORONLY 
ULONG flFlags 


window, it must be subclassed to 
receive the WM_HELP message. 

The initial font displayed is created 
based on the contents of the fAttrs 
parameter. For a complete discussion of 
the FATTRS structure, see Chapter 7. 
The dialog is created modeless; the 
default is to create a modal dialog. 
When this flag is used, the 
WlnFontDlg returns the window 
handle of the created dialog. 

Fonts displayed in the dialog are not 
synthesized. Attributes such as bold or 
italic will not be added to base fonts. 

A WM_DRAWITEM message is sent 
to the owner window allowing it to 
render the preview window. If this 
message is not processed, the default 
processing of the preview window 
occurs. The Outline, Underline, and 
Strikeout buttons are created as three 
state check boxes. 

Only enumerate proportional fonts in 
the dialog. A Font is proportional if 
characters vary in width. For example, a 
capital “A” will be wider than a lower 
case “i.” 

The Reset pushbutton is added to the 
dialog. When it is pushed, the dialog is 
reset to the values it was initialized 
with. 

Only enumerate outline fonts in the 
dialog. 

Additional flags that control the initial 
display of printer or screen fonts in the 
dialog. The default behavior is to 
display fonts enumerated from the 
screen and, if a PS for a print device is 
supplied, display printer fonts. These 
flags will disable the display of printer 
or screen fonts. One or both of these 
flags may be supplied as input. 
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FNTF_NOVIEWSCREENFONTS 


FNTFJMOVIEWPRINTERFONTS 


FNTF_SCREENFONTSELECTED 

FNTF_PRINTERFONTSELECTED 

ULONG flType 


Do not display fonts enumerated from 
the screen PS. The user may override by 
checking the Display check box in the 
dialog. 

If a PS for a print device is supplied, do 
not display fonts enumerated from that 
device. The user may override by 
checking the printer check box. If 
hpsPrinter is NULL, printer fonts are 
not displayed, the printer check box is 
disabled, and this flag has no effect. If 
the dialog was dismissed by selecting 
Ok, one of these two flags will be set. 
They have no effect as an input 
parameter. 

A screen font was selected in the dialog. 
A printer font was selected in the 
dialog. 

If a font was selected, this parameter 
will contain a facename attribute. This 
flag should be used as input to 
GpiQueryFaceString to create a 
compound facename that may be 
passed to GpiCreateLogFont: 


FTYPEJTALIC 

Oxl 

FTYPE_ITALIC_DONT_CARE 

0x2 

FTYPE_OBLIQUE 

0x4 

FTYPE_OBLIQUE_DONT_CARE 

0x8 

FTYPE_ROUNDED 

0x10 

FTYPE_ROUNDED_DONT_CARE 

0x20 


ULONG flTypeMask When the 

FNTS_OWNERDRAWPREVIEW 
flag is set in the f 1 parameter, this field 
contains a mask of the type bits to use. 

ULONG flStyle If a font was selected, this parameter 

will contain flags based on the selected 
emphasis check boxes in the dialog. 
When creating the font, the fsSelection 
field of the FATTRS structure should 
be set to the contents of flStyle: 
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FATTR_SEL_UNDERSCORE 

0x2 

FATTR_SEL_OUTLINE 

0x8 

FATTR_SEL_STRIKEOUT 

0x10 


ULONG flStyleMask When the 

FNTS_OWNERDRAWPREVlEW 

flag is set in the fl parameter, this field 
contains a mask of the style bits to use. 

The next two parameters control the color text display in the font preview window. 
When the FNTS_OWNERDRAWPREVIEW flag is set in the f 1 parameter, the CLR_NOINDEX 
value may be used to leave alone the foreground and background colors. The PM docu¬ 
mentation states that the color value may be an indexed or RGB color value based on the 
color mode hpsScreen is set to. Only indexed colors seem to work: 


LONG 

clrFore 

Foreground (text) color of the font in 



the preview window. 

LONG 

clrBack 

Background color of the text in the font 



preview window. 

ULONG 

ulUser 

Unused field reserved for application 

LONG 

IReturn 

use. 

WinDefFontDlgProc will set this value 


to the ID of the control that resulted in 
the dismissal of the dialog. It is not the 
result value passed to the 
WinDismissDlg function. If your 
custom dialog callback calls 
WinDismissDlg, it must still set the 
ulReturn field to the desired control 
ID. 

LONG 1SRC If the WinFontDlg function fails, this 

field will contain one of the following 
error codes: 

FNT S_ERR_IN VALI D_D IALO G 

FNTS_ERR_ALLOC_SHARED_MEM 

FNTS_ERR_INVALID_PARM 

FNTS_ERR_OUT_OF_MEMORY 

FNTS_ERR_INVALID_VERSION 

FNT S_ERR_D IALO G_LO AD_ERRO R 

If a font is selected, the following three parameters will contain font-sizing informa¬ 
tion taken from the FONTMETRIC structure of the selected font. They are not required to 
create a font of this type and are returned for informational purposes: 
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LONG 

lEmHeight 

When the dialog is dismissed, this param¬ 
eter is updated with Em height of the 
current font. 

LONG 

lXHeight 

When the dialog is dismissed, this param¬ 
eter is updated with X height of the current 
font. 

LONG 

lExternalLeading 

When the dialog is dismissed, this param¬ 
eter is updated with external leading of the 
current font. 

HMODULE 

hMod 

If the FNTS_CUSTOM flag is set, 
WinFontDlg will attempt to load a dialog 
resource with the ID specified in the 
usDlgld field from this module. If hMod is 
NULL, the current executable is searched. 

FATTRS 

fAttrs 

If a font is selected, the FATTRS of the 
selected font will be returned in this para¬ 
meter. If the FNTSJNITFROMFATTRS 
flag is set in the fl field, this is used as an 
input parameter to select the initial font to 
be displayed in the preview window. 

SHORT 

sN ominalPointSize 

When the dialog is dismissed, this param¬ 
eter is updated with nominal point size of 
the font. For Image fonts, this will be the 
font height. For Outline fonts, this is the 
size the font was designed to be rendered. 
The size is returned in decipoints that are 
1/720 inch. To convert to points, divide 
by 10. 


If a font was selected, the following two parameters will contain weight and width 
flags that should be used as input to the GpiQueryFaceString function. It will create a 
compound facename that may be passed to GpiCreateLogFont: 

USHORT us Weight Return parameter that indicates the 

thickness of the strokes used in the 
characters of the font. The most common 
font weights are normal and bold: 

FWEIGHT_ULTRA_LIGHT 

FWEIGHT_EXTRA_LIGHT 

FWEIGHT_LIGHT 

FWEIGHT_SEMI_LIGHT 
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FWEIGHT_NORMAL 

FWEIGHT_SEMI_BOLD 

FWEIGHT_BOLD 

FWEIGHT_EXTRA_BOLD 

FWEIGHT_ULTRA_BOLD 

USHORT us Width Return parameter that describes the width 

of characters in this font: 

FWIDTH_ULTRA_CONDENSED 
FWIDTH_EXTRA_CONDENSED 
FWIDTH_CONDENSED 
FWIDTH_SEMI_CONDENSED 
FWIDTH_NORMAL 
FWIDTH_SEMI_EXPANDED 
FWIDTH_EXPANDED 
FWIDTHJEXTRAJEXPANDED 
FWIDTH_ULTRA_EXPAN DED 

Screen X dialog coordinate; ignored if 
the FNTS_CENTER flag is used. Upon 
return, X is updated to the last screen X 
position regardless of the FNTS_CENTER 
flag. 

Screen Y dialog coordinate; ignored if 
the FNTS_CENTER flag is used. Upon 
return, Y is updated to the last screen Y 
position regardless of the FNTS_CENTER 
flag. 

If the FNTS_CUSTOM flag is set, 
WinFileDlg will attempt to load a dialog 
resource with this ID from the module 
specified in the hMod field. 

Size of the pszFamilyname in bytes. It is 
recommended that pszFamilyname be at 
least FACESIZE in length. 

Reserved parameter must be NULL. 


SHORT x 

SHORT y 

USHORT usDlgld 

USHORT us Family BufLen 

USHORT usReserved 


Basic File Dialog 

The common file dialog provides three combo boxes that allow selection of various font 
facenames, styles, and point sizes. A preview window allows the effect of current selec¬ 
tions to be seen. Like the initial file open sample, the first font dialog sample uses the 
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minimum set of parameters to display the dialog. As with the FILEDLG structure, the 
FONTDLG structure must be initialized to zeros and the size of the structure set in the cbSize 
field. An additional buffer that will hold the selected family name upon return must be 
allocated. The buffer pointed to by the pszFamilyname should be at least FACES IZE in 
length. This constant is defined in the toolkit header files as the maximum size of a font 
facename. Unlike the File Open dialog that doubled as the Save As dialog, no flags are 
required by default. We have used the FNTS_CENTER flag in place of specifying the de¬ 
fault X and Y positions of the dialog. Finally, the foreground and background colors used 
in the font preview window must be provided. Here is an example of setting these: 

szFamilyname[0] = 0; 

memset((PCH)&FontDlg,0, sizeof(FONTDLG)); 

FontDlg.cbSize = sizeof(FONTDLG); 

FontDlg.pszFamilyname = szFamilyname; 

FontDlg.usFamilyBufLen = FACESIZE; 

FontDlg.fi = FNTS_CENTER; 

FontDlg.clrFore = CLR_BLACK; 

FontDlg.clrBack = CLR_WHITE; 

WinFontDlg(HWND_DESKTOP,hWndClient,(PFONTDLG)&FontDlg); 
if (FontDlg.IReturn == DID_0K) 

WinSetWindowText(hWndFrame,(PSZ)FontDlg.pszFamilyname); 

The WinFontDlg function returns TRUE if the dialog was successfully created and FALSE 
if an error occurs. If an error occurs, the 1SRC parameter will contain an error code that 
identifies the reason for the failure. The dialog is by default modal and will return from 
the Winf ontDlg function call when the user selects the Ok or Cancel pushbuttons. The 
selected f amilyname will be contained in the pszFamilyname parameter if Ok was se¬ 
lected; otherwise its contents are undefined. If Ok was selected, the font f amilyname is 
set as the titlebar text. 

Changing the Font 

When a file is opened and displayed in the client area, it is output by using the default 
system proportional font. This font requires no creation or selection because it is present 
in the default presentation space unless changed by the application. The second font dialog 
sample will allow the font used to output the file text to be changed. Although the 
f amilyname returned in the first example is interesting, it alone is not sufficient to create 
a font selected in the dialog. Because we are more concerned with how the common font 
dialog is used than with all the interworking of the font creation process, we will cover 
only the basics. Chapter 7 will provide a more in-depth coverage of the font creation 
process. 


150 



Chapter 4r 2.1 Common Dialogs 


Font as Logical Resource 

A font is considered to be a logical resource created by the GpiCreateLogFont function. 
A logical font is a description of a desired font from which PM will select a physical font. 
The font description is comprised of the facename, size, and attributes of a desired font. 
It is from this description that PM will map or choose the closest physical font available. 
A physical font is bitmap images or graphics primitives used to render the font. A new 
logical font is identified by a numeric value called a local identifier. This value is selected 
by the application and must be in the range of 1 to 254. After a logical font is created, the 
physical font it is mapped to will not change. The GpiCreateLogFont function takes 
these four parameters: 

GpiCreateLogFont(hPS,pchName,lcid,pFattrs) 


HPS 

hPS 

The handle to a presentation space in 
which this logical font is to be created. 

PSTR8 

pName 

Pointer to an optional logical font 
name. 

LONG 

ILcid 

The application-supplied local 
identifier to be associated with this 
logical font. 

PFATTRS 

p Fattrs 

Pointer to a FATTRS structure. This 
structure contains the definition of the 
logical font to be created. 


It is the pFatt rs parameter that we are most interested in here. It contains facename, 
sizes, and attributes that describe a logical font. You may recall that the FONTDLG struc¬ 
ture also contains a FATTRS structure. When a font is selected by pressing Ok in the dia¬ 
log, the f Attrs parameter will contain the logical description of the selected font. The 
values returned in the FATTRS may then be passed to the GpiCreateLogFont function. 
When the WinFontDlg function returns and a font has been selected, the FATTRS por¬ 
tion of the FONTDLG is copied to the Fattrs variable in our sample application: 

if (FontDlg.IReturn == DID_0K) 

{ 

set_font((PSZ)FontDlg.pszFamilyname); 

Fattrs = FontDlg.fAttrs; 

} 

The Fattrs variable will be passed to the GpiCreateLogFont function during the 
painting of the client window. After it is created, the local identifier must be set into the 
presentation space before the new logical font is used. This is done by using the 
GpiSetCharSet function. It takes two parameters: the first is the handle to the presenta¬ 
tion space to set the created font into, and the second is the local identifier used when the 
font was created. 
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Now that we have a method of creating a font selected in font dialog, the second 
sample dialog will demonstrate changing the font used to output the text. Several new 
creation flags have been added to the f 1 field of the FONTDLG structure. To simplify the 
creation process, only image fonts will be displayed in the dialog. This is done by setting 
the FNTS_BITMAPONLY flag. The FNTS_RESETBUTTON flag has also been added. It creates 
a pushbutton that, when pushed, returns the dialog to its initial creation state. The most 
important new flag added, however, is the FNTS_INITFROMFATTRS flag. This causes the 
font initially selected in the dialog to be created based on the contents of the f Att r s field 
of the FONTDLG structure. The FATTRS field will be initialized with the values saved from 
the last font selected in the dialog: 


szFamilyname[0] = 0; 

memset((PCH)&FontDlg,0,sizeof(FONTDLG); 


sizeof(FONTDLG); 

WinGetPS(hWnd); 
szFamilyname; 

FACESIZE; 

"Sample Text"; 

FNTS_RESETBUTTON | FNTS_CENTER | 
FNTS_INITFROMFATTRS | FNTS_BITMAPONLY; 
CLR_BLACK; 

CLR_PALEGRAY; 

Fattrs; 
szBuff1; 
set_title(szBuff1,IDS_F0NT); 

WinFontDlg(HWND_DESKTOP,hWndClient,(PFONTDLG)&FontDlg); 


FontDlg.cbSize 
FontDlg.hpsScreen 
FontDlg.pszFamilyname 
FontDlg.usFamilyBufLen 
FontDlg.pszPreview 
FontDlg.fi 

FontDlg.clrFore 
FontDlg.clrBack 
FontDlg.fAttrs 
FontDlg.pszTitle 


The only problem is that, until the dialog is created the first time, Fattrs is 
uninitialized. This variable can be initialized with the default font values during the 
WM_CREATE message. The function used to query the default font attributes does not take 
a pointer to a FATTRS structure, however. The GpiQueryFontMet rics function requires 
a Presentation Space handle and a pointer to a FONTMETRICS structure. Information about 
the font currently selected in PS is returned in the FONTMETRICS structure. The FATTRS 
structure is a subset of FONTMETRICS, and after being initialized to zeros, the default font 
facename and height are copied to the Fattrs variable: 


case WM_CREATE: 

// Query the height of the default font. 

hPS = WinGetPS(hWnd); 

memset(&Fattrs,0,sizeof(FATTRS)); 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS),(PFONTMETRICS)&FontMetrics) 
Fattrs.IMaxBaselineExt = FontMetrics.IMaxBaselineExt; 

Fattrs.usRecordLength = sizeof(FATTRS); 

strcpy((PSZ)Fattrs.szFacename,(PSZ)FontMetrics.szFacename); 
WinReleasePS(hWnd); 
szFilePath[0] = 1 \0 1 ; 
break; 
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The font can now be created in the requested size before outputting the file text during 
the WM_PAINT message: 

GpiCreateLogFont(hPS,NULL,CLIENT_FONT,&Fattrs); 

GpiSetCharSet(hPS,CLIENT_FONT); 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS),(PFONTMETRICS)&FontMetrics) 
cyHeight = FontMetrics.IMaxBaselineExt + FontMetrics.lExternalLeading; 

The set_f ont function has been added to update the titlebar with the current filename 
and font facename. The client window is then invalidated causing the file text to be 
redisplayed. 

Making the Dialog Modeless 

Although we have enabled the user to change the font a file is displayed in, the mecha¬ 
nism is cumbersome. There are two major drawbacks to the solution just presented. The 
first is that the user is required to select Ok and close the dialog to see the changes to the 
font take effect. The font preview window helps, but it won’t show how much of the text 
will fit in the client window. Each change of a font requires the dialog to be opened by 
selecting it from the menu. If the font is being changed frequently, this can become tire¬ 
some. The second problem results from creating the font dialog as modal. The WinFontDlg 
function will not return until the dialog is dismissed. This prevents any other interaction 
with the application while this dialog is displayed. 

The solution to the first problem is to create the dialog with the Apply pushbutton 
by adding the FNTS_APPLYBUTTON flag to the f 1 field of the FONTDLG structure. We will 
also need to add our private dialog callback, FontDlgProc, to handle the processing of 
the Apply button. As with the private file open dialog callback, the previous callback, 
WinDef FontDlgProc, should be called with unprocessed messages. With the exception 
of the function name, the callback function must be defined as follows: 

MRESULT EXPENTRY FontDlgProc(HWND,ULONG,MPARAM,MPARAM); 

When pushed, the Apply pushbutton will send FontDlgProc a WM_COMMAND mes¬ 
sage with the first short value in mpl equal to DID_APPLY_BUTTON. When this message is 
received, the same code that was called in the previous example—when the WinFontDlg 
function returned with IReturn equal to DID_OK —is executed: 

case DID_APPLY_BUTTON: 

set_font(pFontDlg->pszFamilyname); 

Fattrs = pFontDlg->fAttrs; 

return (0); 

break; 

You may recall that this caused the application to add the new font facename to the 
titlebar and to redraw the client area using the new font. The pFontDlg pointer is a static 
variable that was initialized during the WM_INTIDLG message. 
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The solution to the second problem is to create the dialog as modeless rather than 
modal. WinFontDlg will immediately return the dialog handle of the created dialog when 
the FNTS_MODELESS flag is added to the f 1 field. The return value is the handle of the 
dialog if successful and 0 if an error occurs. The user will then be able to interact with the 
main application. For example, the current file may be changed while the font dialog is 
displayed. When creating the dialog as modeless, remember that the FONTDLG structure 
passed to the WinFontDlg function must be valid for the life of the dialog. In the previ¬ 
ous font dialogs, the structure was allocated as a local variable on the stack. When the 
process_command function returned, those variables were no longer valid. A new global 
structure, FontDlg2, is defined and used for the modeless font dialog initialization. 

The dialog may be closed by selection of the Ok or Cancel pushbutton. Because the 
dialog is modeless, it will not return to the caller as was the case in the modal font dialog. 
Any code executed based on IReturn field of the FONTDLG structure must be done in the 
dialog. We must add code to process the WM_COMMAND message from the Ok pushbutton. 
We want to do exactly the same thing for the Ok button processing as was done for the 
Apply button and then cause the dialog to be dismissed. Calling WinDef FontDlgProc 
with the Ok command message will dismiss the dialog and have no effect for the Apply 
command. The code for Ok and Apply button processing can, therefore, be identical: 

case DID_APPLY_BUTTON: 
case DID_OK_BUTTON: 

WinDefFontDlgProc(hWndDlg , ulMessage,mpl,mp2); 
set_font(pFontDlg->pszFamilyname); 

Fattrs = pFontDlg->fAttrs; 

return (0); 

break; 

Although this change gives us the desired behavior for the Ok and Apply buttons, it 
still requires the Apply or Ok buttons to be pushed. What we would like is to have im¬ 
mediate feedback similar to that of the notebook controls. Notebooks typically do not 
have an Ok button to put the changes into effect. When a selection is made, the change 
occurs. For example, the background page of the settings notebook allows a bitmap to be 
used as the background of the desktop or a folder. When a bitmap file is selected in the 
file combination box, the window is updated immediately. A new check box will be added 
to the dialog during the WM_INITDLG message. This check box will enable or disable the 
immediate updating of the client window. The add_checkbox function calculates the 
position of the control and creates the button. Because we know this dialog will have 
only three pushbuttons, the check box is created vertically centered on these rows of 
pushbuttons. The horizontal position is one character to the right of the Cancel button. 
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To update the client window, we must know when changes are made in the dialog. 
FontDlgProc will receive a number of notification messages when selections are made 
that alter the facename, point size, and style attributes. 


Font Notification Messages 

The following are important font notification messages: 


FNTM_FACENAMECHAN GED 


FNTMJFILTERLIST 


FNTIJFAMILYNAME 

FNTIJPOINTSIZE 

FNTI_STYLENAME 


FNTI_BITMAPFONT 

FNTI_DEFAULTLIST 

FNTI_FIXEDWIDTHFONT 

FNTI_PROPORTIONALFONT 

FNTI_SYNTHESIZED 


Sent when the font family name is 
changed by the user. The mp 1 param¬ 
eter will contain a pointer to the 
currently selected facename. The mp2 
parameter will contain zero. 

This message is sent to the dialog before 
strings are added to the family name, 
style name, and point size combo boxes. 
The mpl parameter will contain a 
pointer to the null-terminated string 
being added. The low word of the mp2 
parameter will identify the combo box 
the string is being added to. It may be 
one of the following: 

The string is being added to the family 
name combo box (DID_NAME). 

The string is being added to the point 
size combo box (DID_SIZE). 

The string is being added to the font 
style combo box (DID_STYLE). The 
high word of mp2 contains information 
about the font being added. The high 
word of MP2 contains information 
about the font being added. It will 
contain one or more of the following: 
Font is a bitmap font. 

Font point size is from the default or 
application supplied point size string. 
Font is fixed width. 

Font is proportionally spaced. 

Font style is synthesized. This flag will 
only be set for FNTI_STYLENAME. 
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FNTIJVECTORFONT Font is a vector font.The default 

processing in WinFontDlgProc will add 
the string if it meets the criteria of the fl 
flags set in the FONTDLG structure. If 
the font is added, WinFontDlgProc will 
return TRUE. Otherwise, FALSE is 
returned. 

FNTM_POINTSIZECHANGED Sent when the point size of the font is 

changed by the user. The mp 1 param¬ 
eter will contain a pointer to the text in 
the point size entry field. The mp2 
parameter contains that point size in 
fixed notation. 

FNTM_STYLECHANGED Sent when any one of the style attributes 

such as underline or strikeout are 
changed. The mp 1 parameter will 
contain a pointer to a STYLECHANGE 
structure. It contains information on the 
weight, width, and type of the font 
before and after the user made a change. 
FNTM_UPDATEPREVIEW Sent before the preview window is 

updated. The mp 1 parameter will 
contain the window handle of the 
preview window. The mp2 parameter is 
zero. 

The message that we are most interested in is the FNTM_UPDATEPREVIEW message. It 
is sent after the FONTDLG structure has been updated and before the preview window is 
drawn. If the Direct Update check box is selected when this message is received, the cli¬ 
ent area is updated: 

case FNTMJJPDATEPREVIEW: 

if (WinSendMsg (hWndllpdate, BM_QUERYCHECK, 0,0)) 

{ 

// Update the display window. 

mReturn = WinDefFontDlgProc(hWndDlg,ulMessage,mp1,mp2); 

set_font(pFontDlg->pszFamilyname); 

Fattrs = pFontDlg->fAttrs; 

return (mReturn); 

} 

break; 


156 



Chapter 4 2.1 Common Dialogs 


Owner Draw Preview 

If your application has some special requirements for the preview window, you can pro¬ 
vide your own drawing routine. Setting the FNTS_OWNERDRAWPREVIEW flag in the f 1 field 
of the FONTDLG structure causes a WMJDRAWITEM message to be sent to the dialogs owner 
window whenever the preview window must be updated. Because this message is sent to 
the owner window and not the dialog, it is not necessary to supply your own dialog pro¬ 
cedure. The mpl parameter of the WM_DRAWITEM message will contain the ID of the win¬ 
dow to be updated, in this case DID_SAMPLE. The mp2 parameter is a pointer to an 
OWNERITEM structure. It will contain the window handle of the preview window, 
a Presentation Space handle for the window, a rectangle defining the size preview win¬ 
dow size, and various state flags. The pointer to the FONTDLG structure can be retrieved 
by querying the QWL_USER field of the parent of the preview window. If your application 
draws the preview window, return TRUE; otherwise, return FALSE if you want the dialog 
to draw the item. 


The CONTROL Sample Application 

The following sections contain the source code of the files in the CONTROL sample. 


Files to Build the CONTROL Sample 

COMMDLG.C 

COMMDLG.DEF 

COMMDLG.H 

COMMDLG.ICO 

COMMDLG.RC 

CUSTOM .DLG 


COMMDLG.C 


/* 


Common Dialogs Program 
Chapter 4 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#define INCL_GPI 
#define INCL_D0S 
#define INCL ERRORS 
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#include <os2.h> 

#include <stdlib.h> 

#include "commdlg.h" 
#include "..\common\about.h 


#define DRIVE_REMOVABLE 2 
#define DRIVE_FIXED 3 
#define DRIVE_REMOTE 4 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY FileOpenDlgProc(HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY FontDlgProc(HWND,ULONG , MPARAM,MPARAM); 

HAB hab; 

HWND hWndFrame, 
hWndClient, 
hFontDlg = 0; 

PVOID pMem; 

PCHAR pFileText = 0; 

PAPSZ pDrivesList = 0; 

ULONG ulTextSize = 0; 

ULONG ulDrivesSize = 0; 
int cyHeight; 
char szBuff1[MAX_BUFF]; 
char szFilePath[CCHMAXPATH]; 
char szFamilyname[FACESIZE]; 

ATOM atSavePath; 

HATOMTBL hAtomTable = 0; 

FATTRS Fattrs; 

FONTDLG FontDlg2; 


int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | 

FCF_SIZEBORDER | FCF_MINMAX | 
FCF_SHELLPOSITION | FCF_TASKLIST 
FCF_ICON i FCF_MENU; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

hAtomTable = WinQuerySystemAtomTable(); 
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DosAllocMem((PPVOID)&pMem,0x1000,PAG_READ | PAG_WRITE); 

DosSubSet(pMem,DOSSUB_INIT | DOSSUB_SPARSE_OBJ,8192); 
get_fixed_drives(); 

WinRegisterClass (hab, szClientClass, ClientWndProc, CS_SIZEREDRAW,0) 
WinLoadString (hab, 0, IDS_APPNAME, sizeof(szBuff1), szBuff1); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 
&flFrameFlags,szClientClass, szBuff1, 0 , 0 ,ID_APPNAME,&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 


HWND APIENTRY add_checkbox(HWND hWndDlg) 


This function will create a checkbox button in the lower right 
hand corner of hWndDlg. The dialog is expected to be the standard 
font selection dialog. The button is vertically aligned to the 
center of the OK pushbutton and horizonatally aligned so that all 
of the text is visable in the dialog. 


HWND 

hCheckBox; 

HPS 

hPS; 

RECTL 

DlgRectl; 

RECTL 

ButtonRectl 

int 

iLength; 

PVOID 

pData; 


FONTMETRICS FontMetrics; 

POINTL Ptl[TXTBOX_COUNT + 1]; 

// Get the sizes of the dialog and the cancel pushbutton 
WinQueryWindowRect(hWndDlg,&DlgRectl); 

WinQueryWindowRect(WinWindowFromID(hWndDlg,DID_CANCEL), 
&ButtonRectl); 

WinMapWindowPoints(WinWindowFromID(hWndDlg,DID_CANCEL),hWndDlg, 
(PP0INTL)&ButtonRectl,2); 
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// Load the checkbox text string 
DosSubAlloc(pMem,(PPVOID)&pData,MAX_BUFF); 

iLength = WinLoadString (hab,0,IDS_UPDATE,MAX_BUFF,(PSZ)pData); 

// Get the string extent and the average character width. 
hPS = WinGetPS(hWndDlg); 

GpiQueryTextBox(hPS,iLength,(PSZ)pData,TXTB0X_C0UNT,Ptl); 
GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 
(PFONTMETRICS)&FontMetrics); 

WinReleasePS(hPS); 

// Increase the height of the window by 50% 
Ptl[TXTBOX_TOPRIGHT].y += Ptl[TXTBOX_TOPRIGHT].y / 2; 

// Create the checkbox 

hCheckBox = WinCreateWindow (hWndDlg,WC_BUTT0N,(PSZ)pData, 
WS_VISIBLE | BS_AUTOCHECKBOX | WS_TABSTOP, 
ButtonRectl.xRight + FontMetrics.lAveCharWidth, 
ButtonRectl.yBottom + 

((ButtonRectl.yTop - ButtonRectl.yBottom) / 2) - 
(Ptl[TXTBOX__TOPRIGHT] .y / 2), 

DlgRectl.xRight - ButtonRectl.xRight - 
(FontMetrics.lAveCharWidth +1), 

Ptl[TXTBOX_TOPRIGHT].y, 
hWndDlg,HWND_TOP, DID_UPDATE_FONT,0,0); 
DosSubFree(pMem,pData,MAX_BUFF); 
return (hCheckBox); 


void APIENTRY cleanup() 

/*.*\ 


This function is called to free the memory allocated and destroy 
the application window. 


\*.*/ 

{ 

if (pFileText) 

DosSubFree(pMem,pFileText,ulTextSize); 
if (pDrivesList) 

DosSubFree(pMem,pDrivesList,ulDrivesSize); 

DosFreeMem(pMem); 

WinDestroyWindow (hWndFrame); 
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void APIENTRY get_fixed_drives() 

/*. .. *\ 


This function will enumerate the drives available to this device 
and create papszDriveList parameter of the FILEDLG structure. Only 
nonremovable drives are placed in the list. 


\*.*/ 

{ 

APIRET RetCode; 

ULONG ulBytes; 

PFSQBUFFER2 pfsq; 

HFILE hDrive; 

ULONG ulAction; 

int nDrive; 

char szDrive[3] = " 

PUSHORT pDrives = 0; 

PULONG pStringArray; 

PSZ pDriveLetter; 

// Disable the exception handling when the drive door is open 
DosError (0); 

// Allocate the memory for the pDrives array 

DosSubAlloc(pMem,(PPVOID)&pDrives,sizeof(USHORT) * MAX_DRIVES); 
memset(pDrives,0,sizeof(USHORT) * MAX_DRIVES); 

DosSubAlloc(pMem,(PPVOID)&pfsq,1024); 

// Allocate memory for pDrivesList 

ulDrivesSize = ((MAX_DRIVES + 1) * sizeof(PLONG)) + 

(3 * MAX_DRIVES); 

DosSubAlloc(pMem,(PPVOIDJ&pDrivesList,ulDrivesSize); 
pStringArray = (PULONG)pDrivesList; 
memset((PSZ)pStringArray,0,ulDrivesSize); 
pDriveLetter = (PSZ)pStringArray + ((MAX_DRIVES +1) * 
sizeof(PLONG)); 

for (nDrive = 0; nDrive < MAX_DRIVES; nDrive++) 

{ 

szDrive[0] = (CHAR)(nDrive + 'A'); 
ulBytes = 1024; 

// Query the file system to determine if it is a remote drive 
RetCode = DosQueryFSAttach ((PSZ)szDrive,0L,FSAIL_QUERYNAME, 
(PFSQBUFFER2)pfsq,&ulBytes); 

if (((RetCode == 0) |J (RetCode == ERROR_BUFFER_OVERFLOW)) && 

(pfsq->szName[0] == (UCHAR)szDrive[0])) 
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{ 

if (pfsq->iType == FSAT_REMOTEDRV) 
pDrives[nDrive] = DRIVE_REMOTE; 
else 

pDrives[nDrive] = DRIVE_FIXED; 

} 

else if (RetCode == ERROR_NOT_READY) 

// If drive not ready then assume removable 
pDrives[nDrive] = DRIVE_REMOVABLE; 

//If drive is not remote, determine if it is removeable 
if (pDrives[nDrive] == DRIVE_FIXED) 

{ 

// Open the drive and issue a DSK_BL0CKREIV10VABLE request 
if (IDosOpen ((PSZ)szDrive,(PHFILE)&hDrive,&ulAction, 

0L,0L,FILE_OPEN,OPEN_FLAGS_DASD | OPEN_SHARE_DENYNONE,0L)) 

{ 

USHORT usType = 0; 

BYTE bCmd = 0; 

ULONG cbParmLen = 1L; 

ULONG cbDataLen = 2L; 

if (IDosDevIOCtl (hDrive,8L,32L,(PVOID)&bCmd,1L,&cbParmLen, 
(PV0ID)&usType,2L,&cbDataLen)) 

pDrives[nDrive] = (USHORT)((usType == 0) ? DRIVE_REMOVABLE: 
DRIVE_FIXED); 

else 

pDrives[nDrive] = 0; 

} 

DosClose (hDrive); 

} 

if (pDrives[nDrive] == DRIVE_FIXED) 

{ 

// Only add fixed drives to the drives list 
*pStringArray = (ULONG)pDriveLetter; 
pStringArray++; 

*pDriveLetter++ = (nDrive + 'A'); 

*pDriveLetter++ = ': 1 ; 
pDriveLetter++; 

} 

// Reenable exception handling 
DosError (1); 

// Free Temp memory 

DosSubFree(pMem,pDrives,sizeof(USHORT) * MAX_DRIVES); 
DosSubFree(pMem,(PVOID)pfsq,1024); 
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void APIENTRY load_file(PSZ pFileName) 

/*.*\ 


This function is called to open pFileName, allocate memory, read 
the file into memory, and close the file. If an error occurs, a 
message box is posted a string loaded from the resource. 


\*. . */ 

{ 

ULONG i; 

FILESTATUS FileStat; 

HFILE hFile; 

ULONG ulAction; 

if (!DosOpen(pFileName,(PHFILE)&hFile,(PULONG)&ulAction,0, 

FILE_N0RMAL,FILE_OPEN, 

OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE,0) ) 

{ 

if (pFileText) 

{ 

DosFreeMem(pFileText); 
pFileText = 0; 
ulTextSize = 0; 

} 

if (!DosQueryFileInfo(hFile,1,(PVOID)&FileStat, 

Sizeof(FILESTATUS))) 

{ 

ulTextSize = FileStat.cbFileAlloc; 

if (DosAllocMem((PPVOID)&pFileText,ulTextSize,fALLOC)) 

{ 

ulTextSize = 0; 
pFileText = 0; 

post_error(hWndClient,IDS_MEMORY_ERROR); 

DosClose(hFile); 
return; 

} 

} 

if (DosRead(hFile,(PVOID)pFileText,UlTextSize,(PULONG)&ulAction)) 

{ 

post_error(hWndClient,IDS_READ_ERROR); 

WinInvalidateRect(hWndClient,0,FALSE); 

> 

else 

{ 

for (i = 0; i < ulTextSize;i++) 

{ 

// Remove NULL characters and carrige returns, 
if (*(pFileText + i) == 0) 
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*(pFileText + i) = 1 1 ; 
if (*(pFileText + i) == 0xD) 

*(pFileText + i) = ' 1 ; 

} 

strcpy((PSZ)szFilePath,pFileName); 
set_font ((PSZ)Fattrs.szFacename); 

} 

DosClose(hFile); 

} 

else 

post_error(hWndClient,IDS_0PEN_ERR0R); 


USHORT APIENTRY post_error(HWND hWnd,USHORT usErrorlD) 

/*.*\ 


This is a utility function which will post a message box with 
a string loaded from the resource file. 


\*.*/ 

{ 

WinLoadString (hab 3 0 3 usErrorID 3 MAX_BUFF 3 szBuff1); 
return ((USHORT)WinMessageBox(HWND_DESKTOP 3 hWnd 3 (PSZ)szBuff1 3 
(PSZ)"Error" 3 0,MB_OK | MB_ICONHAND | MB_APPLMODAL)); 

} 


void APIENTRY process_command(HWND hWnd,MPARAM mpl 3 MPARAM mp2) 

/*.*\ 


All WM_COMMAND messages received by the client window will be 
processed here. 


\* . */ 

{ 

FILEDLG FileDlg; 

FONTDLG FontDlg; 

switch(SH0RT1FR0MMP(mpl)) 

{ 

case IDM_0PEN1: 

// Create the default file open dialog, 
memset(&FileDlg 3 0 3 sizeof(FILEDLG)); 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.fi = FDS_CENTER | FDS_OPEN_DIALOG; 

WinFileDlg(HWND_DESKTOP 3 hWndClient 3 (PFILEDLG)&FileDlg); 
if (FileDlg.IReturn == DID_0K) 

WinSetWindowText(hWndFrame,(PSZ)FileDlg.szFullFile); 
break; 
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case IDM_0PEN2: 

memset(&FileDlg,0,sizeof(FILEDLG)); 
set_title(szBuff1, IDS_0PEN); 

FileDlg.pszTitle = szBuff1; 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.fi = FDS_OPEN_DIALOG | FDS_CENTER; 

FileDlg.papszIDriveList = pDrivesList; 

WinLoadString (hab,0,1DS_PATH,CCHMAXPATH, 

(PSZ)&FileDlg.szFullFile); 

WinFileDlg (FIWND_DESKTOP, hWndClient, (PFILEDLG)&FileDlg); 
if (FileDlg.IReturn == DID_OK) 

load_file((PSZ)&FileDlg.szFullFile); 
break; 

case IDM_0PEN3: 

// Create a dialog with a custom dialog template and callback, 
memset(&FileDlg 3 0 3 sizeof(FILEDLG)); 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.pszTitle = szBuff 1 ; 

FileDlg.fi = FDS_OPEN_DIALOG | FDS_CUSTOM ] FDS_CENTER; 

FileDlg.hMod = 0; 

FileDlg.usDlgld = OPEN_DIALOG; 

FileDlg.ulUser = atSavePath; 

FileDlg.pfnDlgProc = (PFNWP)FileOpenDlgProc; 
set_title(szBuff1,IDS_OPEN); 

set_path((PSZ)FileDlg.szFullFile,FDS_OPEN_DIALOG); 

WinFileDlg(HWND_DESKTOP 3 hWndClient,(PFILEDLG)&FileDlg); 
if (FileDlg.IReturn == DID_OK) 

{ 

if (atSavePath) 

atSavePath = WinDeleteAtom(hAtomTable,atSavePath); 
if (FileDlg.ulUser == DID_SAVE_DIR) 

atSavePath = WinAddAtom(hAtomTable 3 (PSZ)FileDlg.szFullFile) ; 
load_file((PSZ)&FileDlg.szFullFile); 

} 

break; 


case IDM_SAVEAS1: 

memset(&FileDlg 3 0 3 sizeof(FILEDLG)); 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.pszTitle = szBuff1; 

FileDlg.fi = FDS_CENTER | FDS_SAVEAS_DIALOG J 

FDS_ENABLEFILELB; 
set_title(szBuff1,IDS_SAVE); 

strcat((PSZ)FileDlg.szFullFile,(PSZ)szFilePath); 
WinFileDlg(HWND_DESKTOP,hWndFrame,(PFILEDLG)&FileDlg); 
if (FileDlg.IReturn == DID_OK) 
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{ 

WinSetWindowText(hWndFrame,(PSZ)FileDlg.szFullFile); 

// Code to perform file save operation would go here. 

} 

break; 

case IDM_F0NT1: 

szFamilyname[0] = 0; 

memset((PCH)&FontDlg,0,sizeof(FONTDLG)); 

FontDlg.cbSize = sizeof(FONTDLG); 

FontDlg.pszFamilyname = szFamilyname; 

FontDlg.usFamilyBufLen = FACESIZE; 

FontDlg.fi = FNTS_CENTER; 

FontDlg.clrFore = CLR_BLACK; 

FontDlg.clrBack = CLR_WHITE; 

WinFontDlg(HWND_DESKTOP,hWndClient,(PFONTDLG)&FontDlg); 
if (FontDlg.IReturn == DID_OK) 

WinSetWindowText(hWndFrame,(PSZ)FontDlg.pszFamilyname); 
break; 

case IDM_F0NT2: 

szFamilyname[0] = 0; 
memset((PCH)&FontDlg,0 
FontDlg.cbSize 
FontDlg.hpsScreen 
FontDlg.pszFamilyname 
FontDlg.usFamilyBufLen 
FontDlg.pszPreview 
FontDlg.fi 

FontDlg.flStyle 
FontDlg.clrFore 
FontDlg.clrBack 
FontDlg.fAttrs 
FontDlg.pszTitle 
set_title(szBuff1,IDS_FONT); 

WinFontDlg(HWNDJDESKTOP,hWndClient,(PFONTDLG)&FontDig); 
if (FontDlg.IReturn == DID_OK) 

{ 

set_font((PSZ)FontDlg.pszFamilyname); 

Fattrs = FontDlg.fAttrs; 

} 

WinReleasePS(FontDlg.hpsScreen); 
break; 

case IDM_F0NT3: 

szFamilyname[0] = 0; 

memset((PCH)&FontDlg2,0,sizeof(FONTDLG)); 

FontDlg2.hpsScreen = WinGetPS(hWnd); 

FontDlg2.cbSize = sizeof(FONTDLG); 


, sizeof(FONTDLG)); 

= sizeof(FONTDLG); 

= WinGetPS(hWnd); 

= szFamilyname; 

= FACESIZE; 

= "Sample Text"; 

= FNTS_RESETBUTTON | FNTS_CENTER | 

FNTS_INITFROMFATTRS | FNTS_BITMAPONLY 
= FATTR_SEL_ITALIC; 

= CLR_BLACK; 

= CLR_PALEGRAY; 

= Fattrs; 

= szBuff 1; 
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FontDlg2.pszFamilyname 
FontDlg2.usFamilyBufLen 
FontDlg2.pszPreview 
FontDlg2.pfnDlgProc 
FontDlg2.clrFore 
FontDlg2.clrBack 
FontDlg2.f1 


szFamilyname; 
FACESIZE; 

"Sample Text"; 
FontDlgProc; 
CLR_BLACK; 
CLR_PALEGRAY; 
FNTS_CENTER | 
FNTS_INITFROMFATTRS 
FNTS_BITMAPONLY | 
FNTS_APPLYBUTTON | 
FNTS_MODELESS; 

FontDlg2.fAttrs = Fattrs; 

FontDlg2.pszTitle = szBuff1; 

set_title(szBuff1,IDS_FONT); 
hFontDlg = WinFontDlg (HWNDJDESKTOP, hWndClient, 
(PFONTDLG)&FontDlg2); 
if (!hFontDlg) 

post_error(hWnd,IDS_FONTDLG_ERROR); 
break; 


case IDM_AB0UT: 

WinLoadString (hab, 0, IDS_APPNAME, sizeof(szBuff1), szBuff1) 

DisplayAbout (hWnd, szBuffl); 

break; 

default: 
break; 

} 

return; 
mp2; 


void APIENTRY set_font(PSZ pFacename) 

/* ... 


This function will set a new titlebar text string. The string is 
comprised of the filename of the displayed file followed by the 
facename of the font that the file is displayed in. The client 
window is then invalidated. This function should be called after 
the font is changed. 


{ 

ULONG ulSize; 

PVOID pData; 
if (szFilePath[0]) 

{ 

ulSize = strlen(szFilePath); 
ulSize += strlen(pFacename); 
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DosSubAlloc(pMem,(PPVOID)&pData,ulSize); 
strcpy(pData,szFilePath); 

WinLoadString (hab,0,IDS_DASH,MAX_BUFF,szBuff1); 
strcat(pData,szBuff1); 
strcat(pData,pFacename); 

WinSetWindowText(hWndFrame,(PSZ)pData); 
DosSubFree(pMem,pData,ulSize); 


} 

else 


WinSetWindowText(hWndFrame,pFacename); 
WinlnvalidateRect(hWndClient,0,FALSE); 


void APIENTRY set_path(PSZ pFileSpec,USHORT usType) 

/*.*\ 


This function will initialze pFileSpec with a path and file spec 
based on the contents of atSavePath atom. If it is NULL, the default 
file spec is loaded; otherwise the atom text is retrieved. 


\* */ 

{ 

char szBuff[MAX_BUFF]; 

ULONG ulSize; 

PVOID pData; 

PCHAR pChar; 

WinLoadString (hab,0,IDS_PATH,MAX_BUFF, szBuff); 
if (atSavePath && 

(ulSize = WinQueryAtomLength(hAtomTable,atSavePath) +1)) 

{ 

DosSubAlloc(pMem,(PPVOID)&pData,ulSize); 

if(WinQueryAtomName (hAtomTable,atSavePath,pData,ulSize)) 

{ 

if (usType == FDS_OPEN_DIALOG) 

{ 

// Find the beginning of the filename. 
pChar = (PCHAR)pData + ulSize - 1; 
while ((*pChar != 1 W) && (pChar != pData)) 
pChar — ; 

if (*pChar == 1 \\ 1 ) 

{ 

pChar++; 

*pChar = '\0 1 ; 

} 

strcat(pData,szBuff); 

} 

strcpy (pFileSpec,(PSZ)pData); 

} 

DosSubFree(pMem,pData,ulSize); 
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} 

else 

strcat(pFileSpec,szBuff); 


void APIENTRY set_title(PSZ pTitle,USHORT usType) 

/*.-.-.*\ 


This function will build a dialog title string in the memory 
pointed to by pTitle. The string is comprised of the application 
name followed by a hyphen followed by the name of the dialog. The 
usType parameter is the string id of the dialog name. All resources 
are loaded from the string table in the resource file. 


\*.- . */ 

{ 

char szBuff[MAX_BUFF]; 

WinLoadString (hab,0,IDS_APPNAME,MAX_BUFF,pTitle); 

WinLoadString (hab,0,IDS_DASH,MAX_BUFF,szBuff); 
strcat(pTitle,szBuff); 

WinLoadString (hab, 0, usType, MAX__BUFF, szBuff); 
strcat(pTitle,szBuff); 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

/*.*\ 


This is the callback which handles the messages necessary to 
maintain the client window. 


\*.-.*/ 

{ 

static RECTL Recti; 

HPS hPS; 

int iDrawn; 

int iTotalDrawn; 

LONG lHeight; 

BOOL bHandled = TRUE; 

FONTMETRICS FontMetrics; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_CREATE: 

// Query the height of the default font. 
hPS = WinGetPS(hWnd); 
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memset(&Fattrs,0,sizeof(FATTRS)); 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 

(PFONTMETRICS)&FontMetrics) ; 

Fattrs.IMaxBaselineExt = FontMetrics.IMaxBaselineExt; 

Fattrs.usRecordLength = sizeof(FATTRS); 

strcpy((PSZ)Fattrs.szFacename,(PSZ)FontMetrics.szFacename); 

WinReleasePS(hWnd); 

szFilePath[0] = 1 \0 1 ; 

break; 

case WM_PAINT: 

hPS = WinBeginPaint (hWnd,0,0); 

WinFillRect(hPS,&Rectl,CLR_WHITE); 
if (pFileText) 

{ 

GpiCreateLogFont(hPS,0,CLIENT_FONT,&Fattrs); 

GpiSetCharSet(hPS,CLIENT_FONT); 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 

(PFONTMETRICS)&FontMetrics); 
cyHeight = FontMetrics.IMaxBaselineExt + 

FontMetrics.lExternalLeading; 
lHeight = Recti.yTop; 
for (iTotalDrawn = 0; 

(iTotalDrawn < ulTextSize) && (Recti.yTop > 0); 
Recti.yTop -= cyHeight) 

{ 

iDrawn = WinDrawText(hPS, 

min (0x1000,(ulTextSize - iTotalDrawn)), 
pFileText + iTotalDrawn, 

(PRECTL)&Rectl,CLR_BLACK,CLR_WHITE, 

DT_LEFT | DT_T0P | DT_WORDBREAK); 
if (iDrawn) 

iTotalDrawn += iDrawn; 
else 

iTotalDrawn++; 

} 

Recti.yTop = lHeight; 

GpiDeleteSetld(hPS,CLIENT_FONT); 

} 

WinEndPaint (hPS); 
break; 

case WM_SIZE: 

Recti.xLeft = Recti.yBottom = 0; 

Recti.xRight = SH0RT1FR0MMP(mp2); 

Recti.yTop = SH0RT2FR0MMP(mp2); 
break; 
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case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl),PV0IDFR0MMP(mp2),CLR_WHITE); 

mReturn = MRFROMLONG(OL); 

break; 

case WM_COMMAND: 

process_command(hWnd,mp1 ,mp2); 
break; 

case WM_DESTROY: 
cleanup(); 
break; 

default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd 3 msg,mp1,mp2); 
return (mReturn); 


} 


MRESULT EXPENTRY FileOpenDlgProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2 ) 

/* *\ 


This dialog callback will handle the save directory option added 
to a standard or custom file open dialog. All other processing is 
handled by WinDefFildDlgProc. 


\*.*/ 

{ 

PFILEDLG pFileDlg; 

switch (ulMessage) 

{ 

case WM_INITDLG: 

// Determine if the save directory button should be checked. 
pFileDlg = (PFILEDLG)WinQueryWindowULong(hWndDlg,QWL_USER); 
if (pFileDlg->ulUser) 

WinCheckButton(hWndDlg,DID_SAVE_DIR,1); 
break; 
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case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_0K: 
case DID_CANCEL: 

if(WinQueryButtonCheckstate(hWndDlg,DID_SAVE_DIR)) 

{ 

// Do the default processing 
WinDefFileDlgProc(hWndDlg,ulMessage,mp1,mp2); 

// Get the pointer to the FILEDLG structure 
pFileDlg = (PFILEDLG)WinQueryWindowULong(hWndDlg, 
QWL_USER); 

pFileDlg->ulUser = DID_SAVE_DIR; 
return (0); 

} 

break; 

} 

break; 

} 

return (WinDefFileDlgProc(hWndDlg,ulMessage,mpl,mp2)); 


MRESULT EXPENTRY FontDlgProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2 ) 

/*.*\ 


This dialog callback will handle the apply button and update 
checkbox which is added during the WM_INITDLG message. All 
other processing is handled by WinDefFontDlgProc. 


\*.*/ 

{ 

static PFONTDLG pFontDlg; 
static HWND hWndUpdate; 

MRESULT mReturn; 

switch (ulMessage) 

{ 

case WM_INITDLG: 

pFontDlg = (PFONTDLG)WinQueryWindowULong(hWndDlg,QWL_USER); 

hWndUpdate = add_checkbox(hWndDlg); 

break; 

case FNTMJJPDATEPREVIEW: 

if(WinSendMsg(hWndUpdate,BM_QUERYCHECK, 0, 0)) 

{ 
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// Update the display window. 

mReturn = WinDefFontDlgProc(hWndDlg 3 ulMessage,mp1 ,mp2); 
set_font(pFontDlg->pszFamilyname); 

Fattrs = pFontDlg->fAttrs; 
return (mReturn); 

} 

break; 

case WM_COMMAND: 

switch (SH0RT1FROMMP(mpl)) 

{ 

case DID_APPLY_BUTTON: 
case DID_0K_BUTT0N: 

WinDefFontDlgProc(hWndDlg,ulMessage,mp1 3 mp2); 
set_font(pFontDlg->pszFamilyname); 

Fattrs = pFontDlg->fAttrs; 

return (0); 

break; 

} 

break; 

} 

return (WinDefFontDlgProc(hWndDlg,ulMessage,mp1,mp2)); 

} 


COMMDLG.H 


/* 


Common Dialogs Header File 
Chapter 4 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define MAX_BUFF 128 
#define MAX_DRIVES 26 
#define ID_APPNAME 1 

#define MAIN_MENU 1 

#define IDM_0PEN1 10 
#define IDM_0PEN2 11 
#define IDM_0PEN3 12 
#define IDM_SAVEAS1 13 
#define IDM_AB0UT 14 

#define IDM_F0NT1 20 
#define IDM_F0NT2 21 
#define IDM F0NT3 22 
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#define 

IDS_APPNAME 

1 



#define 

IDS_OPEN 

2 



#define 

IDS_SAVE 

3 



#define 

IDS_F0NT 

4 



#define 

IDS_DASH 

5 



#define 

IDS_PATH 

6 



#define 

IDS_UPDATE 

7 



#define 

IDS_0PEN_ERR0R 

8 



#define 

IDS MEMORY ERROR 

9 



#define 

IDS_READ_ERROR 

10 



#define 

IDS_FONTDLG_ERROR 

11 



#define 

OPEN_DIALOG 


10 


#define 

DID_FILENAME_TXT 
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#define 

DID_FILENAME_ED 


258 


#define 

DID_DRIVE_TXT 


259 


#define 

DID_DRIVE_CB 


260 


#define 

DID_FILTER_TXT 


261 


#define 

DID_FILTER_CB 


262 


#define 

DID_DIRECTORY_TXT 

263 


#define 

DID DIRECTORY_LB 


264 


#define 

DID FILES TXT 


265 


#define 

DID_FILES_LB 


266 


#define 

DID_HELP_PB 


267 


#define 

DID_APPLY_PB 


268 


#define 

DID OK PB 


DID_ 

OK 

#define 

DID CANCEL PB 


did] 

CANCEL 


#define CLIENT_FONT 2 

#define DID_SAVE_DIR WMJJSER 

#define DID UPDATE FONT WM USER 


HWND 

void 

void 

void 

USHORT 

void 

void 

void 

void 


APIENTRY add_checkbox(HWND); 

APIENTRY cleanup(void); 

APIENTRY get_fixed_drives(void); 

APIENTRY load_file(PSZ); 

APIENTRY post_error(HWND,USHORT); 

APIENTRY process_command(HWND,MPARAM,MPARAM); 
APIENTRY set_font(PSZ); 

APIENTRY set_path(PSZ,USHORT); 

APIENTRY set_title(PSZ,USHORT); 
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COMMDLG.RC 


/* 


Common Dialogs Resource File 
Chapter 4 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WINSTDDLGS 
#include <os2.h> 

#include "commdlg.h" 

RCINCLUDE custom.dig 
RCINCLUDE ..\common\about.dig 


CUSTOM .DLG 


/* 


Custom File Open Dialog 
Chapter 4 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE OPEN_DIALOG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Open File", OPEN_DIALOG, 27, 16, 277, 130, FS_SCREENALIGN 
WS_VISIBLE, FCF_SYSMENU J FCF_TITLEBAR 


BEGIN 

LTEXT "Open Filename:", DID_FILENAME_TXT, 7, 119, 113, 8 

ENTRYFIELD "", DID_FILENAME_ED, 8, 108, 260, 8, ESJVIARGIN 
LTEXT "Drive:", DID_DRIVE_TXT, 7, 96, 64, 8 

CONTROL DID_DRIVE__CB, 6, 60, 90, 35, WC_C0MB0B0X, 

CBS_DROPDOWNLIST | WS_GROUP \ WS_TABSTOP \ 

WS VISIBLE 


LTEXT 

CONTROL 

LTEXT 

LISTBOX 

LTEXT 

LISTBOX 

PUSHBUTTON 

PUSHBUTTON 

AUTOCHECKBOX 


"File Type:", DID_FILTER_TXT, 111, 96, 68, 8 

DID_FILTER_CB, 108, 60, 162, 35, WC_COMBOBOX, 
CBS_DROPDOWNLIST | WS_TABSTOP | WS_VISIBLE 
"Directory:", DID_DIRECTORY_TXT, 7, 72, 78, 8 
DID_DIRECTORY_LB, 7, 23, 89, 54, LS_HORZSCROLL 
"Files:", DID_FILES_TXT, 111, 72, 72, 8 
DID_FILES_LB, 108, 23, 162, 48, LS_HORZSCROLL 
"~Ok", DID_OK, 7, 4, 40, 14, WS_GROUP | BS_DEFAULT 
"-Cancel", DID_CANCEL, 60, 4, 40, 14 
"Save Directory", DID_SAVE_DIR, 179, 5, 84, 10, 

WS GROUP 


END 
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COMMDLG.DEF 

NAME CONTROL WINDOWAPI 

DESCRIPTION 'OS/2 Common Dialogs Blain, Delimon, & English, 1993' 
STACKSIZE 32768 
EXPORTS ClientWndProc 

AboutDlgProc 
FileOpenDlgProc 
FontDlgProc 




Menus 
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Introduction 

Menus are generally the command interface for windowing applications. A menu is sim¬ 
ply a list of items from which the user can easily pick a command or operation. Menus 
are not just “special” areas within a frame window. Menus in OS/2 are, in fact, windows 
themselves. Their nature and operation are similar to other windows; they are frame control 
windows with a specifically defined behavior. 

An application developer has tremendous control over the 
appearance of the menus. Most programmers and users who 
are familiar with windowing applications expect menus to be 
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lists of text that represent choices. However, in OS/2, menu items can be much more 
than that. Menus are windows that contain list of items. These items can be strings, 
bitmaps, or application-drawn pictures. Menu items can be added, changed, or deleted 
at any time as the application presents different information. They are not static struc¬ 
tures that must remain constantly the same during the execution of the application. 

Menus are windows that are owned by another window. This owner window is gen¬ 
erally a frame window. Each of the items in the menu is given a unique identifier by the 
application developer. When the user chooses an item from the menu, this identifier is 
posted in a message to the owner window. Menus are defined most often within the re¬ 
source file that accompanies the application. The examples within this book follow that 
practice. Look for the keyword MENU in the resource files for several of the examples in 
this book. 

Types of Menus 

Menus may be one of several different types. The most common types are discussed in 
this section. 

The predefined window class WC_MENU defines a class of window. This type of win¬ 
dow class presents a list of items to the user for selection. When a menu window is cre¬ 
ated, a block of memory is allocated to hold the list of menu items and the information 
associated with each menu item (see Figure 5.1). 

Associated with every menu item is information that describes its format and posi¬ 
tion in the menu list. The most basic type of menus are top-level menus, which are win¬ 
dows owned by a frame window. These menus are referred to as menu frame controls and 
are assigned an ID of either FID_SYSMENU (0x8002), FID_MINMAX (0x8004), or FID_MENU 
(0x8005). Each of these menus has a different format, but all are top-level menus. 

A menu item can have a submenu associated with it, which is displayed when the 
menu item is selected. When a submenu is defined for a menu item, the window handle 
for that menu is stored in the menu item information. This window handle refers to 
another menu window, which again allocates a block of memory to store the list of menu 
items associated with it (see Figure 5.2.). 

Pull-Down and Cascaded Menus 

A pull-down menu is a submenu that displays when a top-level menu item is selected. 
Pull-down menus have an ID that is defined by the application. If an item in a pull-down 
menu has a submenu defined for it, the submenu is referred to as a cascaded menu. 
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Figure 5.1. 

PM internal menu data 
structure. 


Menu Window Handle 
| 0C30:3F341 


Internal PM Window Structures 



Pop-Up Menus 

A menu can also appear by itself, without being associated with one the menu frame 
controls. This type of menu is referred to as a pop-up menu and usually appears some¬ 
where in the client area of a window or is associated with an icon. 

Menu Components 

The definition of a menu defines a hierarchy of menu items and submenus. Each menu 
item is defined by various styles and attributes. These components are discussed next. 

Menu Hierarchy 

Menu windows have a parent and an owner just like other windows. All top-level menus 
are owned by the application’s frame window and all pull-down and cascaded menus are 
owned by their immediate predecessor in the menu hierarchy. Pop-up menus are owned 
by the window specified as its owner when it is displayed, usually the client window of 
an application. This ownership hierarchy is used to pass menu notification messages from 
one menu window to its owner. 
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Figure 5.2. 

PM internal submenu 
data structure. 


Menu Window Handle 
0C30:3F34 1 


Internal PM Window Structures 


Window 

Data 


Menu Data 
pmenultems - 


Menu Item 1 Data 
hwndSubMenu 
Menu Item 2 Data 
Menu Item 3 Data 


Window 

Data 


Menu Data 
pmenultems 


Menu Item 1 Data 
Menu Item 2 Data 


Notification messages are passed from a menu window to its owner when a menu 
item is selected, a submenu is being displayed, a submenu is being closed, user input is 
received, or to notify the owner of many other window events. For example, when a menu 
is being created, the menu window sends the WM_CONTROLHEAP message to its owner. The 
owner window will either send this up to its owner or return the base address of the heap 
to use to allocate the block of memory required to store the list of menu items. When a 
menu item is selected, a WMJ/1ENUSELECT message is sent to the menu’s owner. If that 
window is another menu, that menu window will send the message up to its owner until 
it reaches a non-menu window. 
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Menu Window Styles 

Menu windows have several flags that identify the type of menu to display. These style 
flags can be set by using: 

WinSetWindowULong (hMenuWnd, QWL_STYLE, ulStyle) 
or queried by using: 

WinQueryWindowllLong (hMenuWnd, QWL_STYLE) 

These styles are set automatically by PM when the menu window is created or loaded, 
but there may be occasion to change these explicitly in the application. For example, if 
you want to take a top-level actionbar menu (MS_ACTIONBAR) and make it a submenu 
item, you would need to explicitly change the style bit so that it would display properly. 

To change an actionbar menu to a pop-up menu, you would perform the following: 

WinSetWindowULong (hWndMenu, QWL_STYLE, 

(WinQueryWindowULong (hWndMenu, QWL_STYLE) & ~MS_ACTIONBAR) | 
MS_POPUP); 

The following is a list of menu styles with their associated value and appearance: 


Style 

Value 

Description 

MS_ACTIONBAR 

0x00000001L 

Menu items are displayed 
side-by-side horizontally. 

ms_titlebutton 

1' 

0x00000002L 

The menu contains one or 
more of the system bitmaps 
(system menu, min button, 
max button, restore button, 
child system menu, close 
button). 

MS_VERTICALFLIP 

0x00000004L 

Pull menu up rather than 
down from menu item. If 
used for an 

MS_ACTIONBAR window, 
all pull-down menus belong¬ 
ing to the actionbar are 
displayed above the menu 
item. 

MS_ROOT 

0x00000008L 

Menu is the root of the menu 
hierarchy. 

MS_POPUP 

0x00000010L 

Menu is a pop-up menu. 


The MS_POPUP style provides a lot of opportunity to do some interesting things. An 
example of MS_P0PUP is included in the sample application for this chapter. 


m 
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Menu Items 

As discussed earlier, a menu is defined by a list of menu items. Each menu item in a menu 
window is defined by an identifier and several styles and attributes. You must understand 
the MENU ITEM structure to understand how each menu item is defined. The MENU ITEM 
structure is defined in pmwin.h as follows: 

typedef struct _MENUITEM { /* mi */ 

SHORT iPosition; 

USHORT afStyle; 

USHORT afAttribute; 

USHORT id; 

HWND hwndSubMenu; 

ULONG hltem; 

} MENUITEM; 

typedef MENUITEM FAR *PMENUITEM; 

The following is a description of each of the parameters: 

IPosition The position of the item in the list of menu items, 

with 0 being the first item in the list. 

afStyle The style of the menu item. This defines what kind 

of data is contained in the menu item and how the 
item is to be drawn. 


Flag 

Value 

MIS_TEXT 

mis_bitmap 

MIS_SEPARATOR 

0x0001 

0x0002 

0x0004 

MIS_OWNERDRAW 

MIS_SUBMENU 

0x0008 

0x0010 

MIS_SYSCOMMAND 

0x0040 

MIS_HELP 

0x0080 

MIS_STATIC 

0x0100 


Description 

Text item. 

Bitmap item. 

Horizontal dividing line (only 
valid for pull-down and pop-up 
menus). 

Item drawn by owner. 

Item contains a pull-down or 
cascading menu window. 

Post a WM_SYSCOMMAND 
message rather than a 
WM_COMMAND message. 
Post a WMJHELP message 
rather than a a 

WM_COMMAND message. 
Information item that cannot be 
selected. 
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Flag Value 

MIS_BUTTONSEPARATOR 0x0200 

MIS_BREAK 0x0400 

MIS_BREAKSEPARATOR 0x0800 


Description 

Menu button item. Items are 
displayed after a separator bar 
and can only be selected with 
the mouse or accelerator key. 
Item is first item in a new row 
or column. 

Same as MIS_BREAK except 
it draws a separator between 
the row or column (only valid 
for pull-down and pop-up 
menus). 


a£4ttribute The attributes of the menu item. This defines how 

the menu item is displayed and whether the item 
can be selected. 


Flag 

MIA_NODISMISS 


MIAJFRAMED 

MIA_CHECKED 

MIAJDISABLED 

MIA_HILITED 

id 


hwndSubMenu 


Value Description 

0x0020 When the item is selected, the 

menu containing this item should 
not be hidden before notifying 
the owner of the selection. 

0x1000 Draw a frame around the item. 

0x2000 Display checkmark next to the 

item. 

0x4000 Item is disabled and cannot be 

selected. 

0x8000 Item is currently selected. 

The identifier for the menu item. While this value 
does not have to be unique, it is recommended so as 
not to produce confusion to the application. Two 
menu items with the same identifier will post the 
same identifier with the WM_COMMAND, 
WM_SYSCOMMAND, or WM_HELP message 
and make it difficult for the application to deter¬ 
mine the selection. 

If the menu item has the MIS_SUBMENU style, 
this field is the window handle of the pull-down or 
cascaded menu. 
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hltem Handle to the object to be displayed for the item. If 

the MIS_BITMAP style is used, this is the handle to 
the bitmap; for MI S_0 WNERD RAW, this can be 
any application defined value. 

A mnemonic is a special way of selecting a menu item when the menu is displayed. 
When a menu is displayed, a menu item with a mnemonic can be selected simply by 
pressing the mnemonic key. The mnemonic character for a menu item is specified by 
preceding the character with a tilde. For example, to specify the character “F” as a mne¬ 
monic for the menu item “File,” it would be defined as “'-File.” 

Specifying Menus In the RC File 

Perhaps the easiest way to define a menu is to do so in the resource file. A menu resource 
is defined in the resource file as follows: 

MENU identifier 

BEGIN 

END 

The identifier uniquely identifies the menu resource. You can substitute braces for 
the BEGIN and END statements. 

MENU identifier 

{ 

} 

Each menu item is defined in the following format: 

MENUITEM text, identifier, style, attribute 

The text field describes the text used for the item or the name of the bitmap resource 
for MIS_BITMAP menu items. If the style or attribute fields are not specified, the item is 
assigned a style of MIS_TEXT, and no attributes are set for the item, indicating that the 
item is enabled. A submenu can be specified with the SUBMENU statement: 

SUBMENU text, identifier, style, attribute 

BEGIN 

END 

The field descriptions are the same as MENUITEM except that you are defining a pull¬ 
down or cascaded menu item. A submenu is defined just as the MENU is defined. The 
following example defines a menu with two pull-down menus and a MIS_HELP menu 
item. The first submenu contains three items with the first item checked and the third 
item specifying a cascaded menu. The second submenu defines two columns of menu 
items with the first item in each column an MIS_STATIC item that cannot be selected: 


.'hv. 
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MENU IDD APPNAME 


{ 


} 


SUBMENU "-Fill", 

{ 

MENUITEM "-Black", 
MENUITEM "-White", 
SUBMENU "-Color", 

{ 

MENUITEM "-Red", 
MENUITEM "-Green", 
MENUITEM "-Blue", 

} 

} 

SUBMENU "-Line Style", 

{ 


IDM_FILL 

IDM_BLACK, 0, MIA_CHECKED 

IDM_WHITE 

IDM_COLOR 

IDM_RED 
IDM_GREEN 
IDM BLUE 


IDM_LINE, MIS TEXT 


MENUITEM "Horizontal", -1, 

MIS_STATIC, MIA_FRAMED 
MENUITEM " Solid", IDM HORZSOLID 


MENUITEM " Dash", 
MENUITEM " None", 
MENUITEM "Vertical", 

MIS_BR EAKS E PARAT0 R 
MENUITEM " Solid", 
MENUITEM " Dash", 
MENUITEM " None", 

} 

MENUITEM "Help", 0, MIS_TEXT 


IDM_HORZDASH, 0, MIA_CHECKED 
IDM_HORZNONE, 

1 , 

MIS_STATIC, MIA_FRAMED 
IDM_VERTSOLID, 

IDM_VERTDASH, 0, MIA_CHECKED 

IDM_VERTNONE 

| MIS_BUTTONSEPARATOR | MISJHELP 


Because the "Horizontal" and "Vertical" menu items are MIS_STATIC items and 
can never be selected, it is okay to assign them the same identifier, in this case -1. 

A pop-up menu can be defined in the resource file in a similar manner. There is no 
special flag to set to define a pop-up menu. The following example defines a pop-up menu 
for selecting a color: 


MENU COLORJ/IENU 

{ 

MENUITEM "-Red", 
MENUITEM "-Blue", 
MENUITEM "-Green", 
MENUITEM "-White", 
MENUITEM "-Black", 

} 


IDM_RED 
IDM_BLUE 
IDM_GREEN 
IDM_WHITE 
IDM BLACK 


Menu Messages 

Messages can be sent to a menu window to cause certain actions to be performed on that 
menu. These include messages to create new menus, add or delete menu items, change 
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menu styles and attributes, and query information about menu items. In addition to the 
many documented messages, many of the undocumented messages are described in lists 
near the end of this chapter. 

As a note, the undocumented messages identified with the BYPOS suffix are currently 
not thunked by PM when the messages are sent. This means that when an address is passed 
as one of the parameters, the message is not recognized as one in which the thunk layer 
must convert the address to a 16-bit address from a 32-bit address. In order to use these 
particular messages, it is necessary for you to perform the conversion in the application 
and pass the 16-bit address to PM. This conversion can be performed by defining the 
following macro and using it whenever you use one of these messages: 

#define MAKE_16BIT_P0INTER(p) (MAKEP(HIUSHORT(p) « 3) 

| 7,LOUSHORT(p))) 

Note that future versions of OS/2 may document and thunk the pointers for these 
messages and thus remove the need for you to convert the pointer. The concept of thunking 
and converting pointers is discussed in detail in Chapter 13, “Calling 16-Bit Code. 55 

For a more thorough discussion of particular messages, consult the lists later in this 
chapter. 

Menu Notification Messages 

There are many messages sent by PM to the menu windows during the course of activat¬ 
ing, drawing, and selecting menus and menu items. Many of these messages make their 
way up the owner chain to the frame or client window. These messages are mostly noti¬ 
fication messages sent to indicate the occurrence of an event or activity. In some cases 
though, these messages are notification messages sent to a menu window to begin a par¬ 
ticular activity. For example, the MM_SUMMON message is sent to a menu window when 
that menu is summoned and is to become active. It is possible for an application to use 
these notification messages to force menu activity for its own purpose. As an example, 
suppose an application wants the system menu to pop up when the user performs a cer¬ 
tain action. The application can send the MM_STARTMENUMODE notification message to 
cause the system menu to appear. 

For a more thorough discussion of particular messages, consult the lists near the end 
of this chapter. 

Menu Item Selection 

When a menu item is highlighted, the WM_MEN US ELECT message is sent to the owner win¬ 
dow. This message either contains the identifier of the currently highlighted menu item 
or the value 0xFFFF. This message can be used by an application to identify or display 
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text related to the item. For example, many applications make use of a “hint” window, 
which is a window displaying a description of the currently selected menu item. When 
the WM_MENUSELECT message is received, the menu item identifier can be used to look up 
a text string and display it in the “hint” window. If the identifier is OxFFFF, this indicates 
that the currently displayed pull-down or cascaded menu is being hidden. 

When a menu item is selected with the mouse or the Enter key and the menu item 
does not have a submenu, the WM_MENUSELECT message is sent with the HIUSHORT ofmpl 
set to 1 . If the application returns TRUE, PM will post either a WM_COMMAND, WM_SYSCOMMAND, 
or WM_HELP message. Returning FALSE will prevent the message from being posted. If 
the MIS_SYSCOMMAND style is set, a WM_SYSCOMMAND message is posted. If the MIS_HELP 
style is set, a WM_HELP message is posted. Otherwise, a WM_COMMAND message is posted. All 
these messages use the identifier of the selected menu item. 


Menu Application 

In our sample application, we will demonstrate all of the features of defining and creat¬ 
ing menus, the various styles of menu items, the use of pop-up menus, and some of the 
undocumented menu messages. This begins with the basics of defining menu items and 
changing their attributes, changing the menu item checkmark, defining bitmap menu 
items, and then how to use owner draw items in pop-up menus. Finally, well look at 
adding entries to the system menu. 


Menu Application Files 

The following are the files necessary to build the menu application: 


MENU.C 

MENU.DEF 

MENU.H 

MENU.ICO 

MENU.RC 

MENUXTRA.H 


Application file. 

Module definition file. 

Application include file. 

Application icon. 

Application resource file. 

This header file contains all the undocumented menu 
messages. We broke this out into a separate file so that 
you could use these in your other applications if you 
desire. 


These are the various bitmap files used for bitmap menu items, checkmarks, and owner 
draw menus. You can use any bitmap editor that is compatible with OS/2 bitmaps to 
open these files and take a look at them. You could even make some modifications to 
them, if you wanted to see these changes in the version of the menu application that you 
create. 
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BMPITEM1.BMP 

BMPITEM2.BMP 

CHECK1.BMP 

CHECK2.BMP 

ODBLUE.BMP 

ODGREEN.BMP 

ODRED.BMP 

UNCHECK1.BMP 

UNCHECK2.BMP 


MENU.C 


/* 


Menu Program 
Chapter 5 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


#define INCLJVIN 
#define INCL_GPI 
#include <os2.h> 

#include <stdio.h> 

#include "menuxtra.h" 

#include "menu.h" 

#include "..\common\about.h" 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 


HAB hab; 

CHAR szTitle[64]; 

CHAR szColor[24]; 

HWND hWndFrame; /* Application Frame window handle 

HWND hWndClient; /* Application Client window handle 

HWND hWndMenu; 

HWND hColorMenu; 

HWND hWndEditMenu; 


/* Attributes set by menu */ 


LONG 

lWindowColor 

= 0X00FFFFFF; 

LONG 

ITextColor 

= 0x00000000; 

LONG 

flCmd 

= DT_CENTER ] DT_VCENTER; 

CHAR 

szText[40] 

= "Menu Text String"; 

USHORT 

AlignFlags[6] 

= { DT LEFT, DT_CENTER, DT_RIGHT, 

DT TOP, DT_VCENTER, DT_BOTTOM }; 

USHORT 

StyleFlags[3] 

= { 0, DT UNDERSCORE, DT_STRIKEOUT } 


*/ 

*/ 
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USHORT 

HAlign 


VAlign 


Style 

LONG 

lColorTable[3] 

BOOL 

bWindowColor 

BOOL 

bUndoAvailable 

BOOL 

bSelected 


IDM_ALIGNCENTER 3 

idm_alignmiddle, 

IDM_STYLENORMAL; 

/* RED GREEN 

{ 0X00FF0000 3 0X0000FF00 
TRUE; 

FALSE; 

FALSE; 


BLUE */ 
0X000000FF }; 


HBITMAP hbmCheckl, 

hbmUnCheckl, 

hbmCheck2 3 

hbmUnCheck2; 


int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | FCF_SIZEBORDER | 
FCF_MINMAX j FCF_SHELLPOSITION | FCF_TASKLIST 
FCF_MENU | FCF_ICON; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab 3 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 

CS_SIZEREDRAW, 0); 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 


hWndFrame = WinCreateStdWindow (HWNDJDESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 


VOID AddAboutToSystemMenu(HWND hWndFrame) 

{ 

MENUITEM mi; 

HWND hWndSysSubMenu; 
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WinSendMsg (WinWindowFromID (hWndFrame, FID_SYSMENU), 
MM_QUERYITEMBYPOS, 0L, MAKE_16BIT_P0INTER(&mi)); 
hWndSysSubMenu = mi.hwndSubMenu; 
mi.iPosition = MIT_END; 
mi.afStyle = MIS_SEPARATOR; 
mi.atAttribute = 0; 
mi.id = -1 ; 

mi.hwndSubMenu = 0; 
mi.hltem = 0; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), NULL); 
mi.afStyle = MIS_TEXT; 
mi.id = IDM_AB0UT; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), 

"About 
return; 

} 

VOID AddBitmapMenu (HWND hWndMenu) 

{ 

MENUITEM mi; 

mi.iPosition = MIT_END; 

mi.afStyle = MIS_TEXT j MIS_SUBMENU; 

mi.afAttribute = 0; 

mi.id = BITMAP_MENU; 

mi.hwndSubMenu = WinLoadMenu (HWND_OBJECT,0,BITMAP_MENU); 
mi.hltem =0; 

WinSendMsg (hWndMenu, MM_INSERTITEM, &mi, "Bitmaps"); 
return; 

} 

VOID AddEditMenuItem (HWND hWndMenu) 

{ 

MENUITEM mi; 

hWndEditMenu = WinCreateMenu (HWND_OBJECT, NULL); 

WinSetWindowUShort (hWndEditMenu, QWS_ID, IDM_EDIT); 

mi.iPosition = MIT_END; 

mi.afStyle = MIS_TEXT; 

mi.afAttribute = MIA_DISABLED; 

mi.id = IDM_UND0; 

mi.hwndSubMenu = 0; 

mi.hltem = 0; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Undo"); 
mi.id = IDM_COPY; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Copy"); 
mi.id = IDM_CUT; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "Cu~t"); 
mi.id = IDM_PASTE; 
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WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Paste"); 

mi.iPosition = 1; 

mi.afStyle = MIS_SEPARATOR; 

mi.afAttribute = 0; 

mi.id = -1; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, ""); 
mi.iPosition = 0; 

mi.afStyle = MIS_TEXT | MIS_SUBMENU; 

mi.afAttribute = 0; 

mi.id = IDM_EDIT; 

mi.hwndSubMenu = hWndEditMenu; 

WinSendMsg (hWndMenu, MM_INSERTITEM, &mi, "-Edit"); 
return; 


VOID DrawOwnerltem (POWNERITEM poi) 

{ 

ULONG yOffset; 

RECTL Recti; 

BITMAPINFOHEADER bmlnfoOwnerDraw; 

ULONG ropCode; 

/* Get the bitmap handle for the bitmap */ 

GpiQueryBitmapParameters ((HBITMAP)poi->hItem,&bmInfoOwnerDraw) 

/* Determine the offset of the portion of the bitmap to draw */ 
if (poi->fsAttribute & MIA_CHECKED) 
yOffset = bmlnfoOwnerDraw.cx / 2; 
else 

yOffset = 0; 

if (poi->fsAttribute & MIAJHILITED) 
yOffset += bmlnfoOwnerDraw.cx / 4; 

/* Determine ROP code to use */ 
if (poi->fsAttribute & MIA_DISABLED) 
ropCode = DBM_HALFTONE; 
else 

ropCode = DBM_NORMAL; 

/* Set the source rectangle and draw the bitmap. */ 

Recti.xLeft = yOffset; 

Recti.yBottom = 0L; 

Recti.xRight = yOffset + bmlnfoOwnerDraw.cx / 4; 

Recti.yTop = bmlnfoOwnerDraw.cy; 

WinDrawBitmap (poi->hps,(HBITMAP)poi->hItem,&Rectl, 

(PPOINTL)&poi->rclltem, 0L, 0L, ropCode); 

/* Turn off attributes by default */ 
poi->fsAttribute = 
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(poi->fsAttributeOld &= ~(MIA_CHECKED | 

MIA_FRAMED)); 

return; 


MIA HILITED 


VOID MeasureOwnerltem (POWNERITEM poi) 

{ 

BITMAPINFOHEADER bmlnfoMenuAttached, 
bmlnfoMenuCheck, 
bmlnfoMenu; 

HBITMAP hbm = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUATTACHED); 
GpiQueryBitmapParameters (hbm,&bmlnfoMenuAttached); 

GpiDeleteBitmap (hbm); 

hbm = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUCHECK); 
GpiQueryBitmapParameters (hbm,&bmlnfoMenuCheck); 

GpiDeleteBitmap (hbm); 

GpiQueryBitmapParameters ((HBITMAP)poi->hItem,&bmInfoMenu); 
poi->rclItem.xRight = (bmlnfoMenu.cx / 4) - 

bmlnfoMenuAttached.cx - bmlnfoMenuCheck.cx; 
poi->rclItem.yTop = bmlnfoMenu.cy; 
return; 

} 

VOID PlacePopup (HWND hWndOwner, HWND hWndMenu, 

ULONG x, ULONG y, BOOL bRight, ULONG ulFlags) 

/* We need to get the height of the menu because WinPopupMenu will 
position the menu with the lower-left corner of the menu at the 
coordinates passed. By sending a WM_ADJUSTWINDOWPOS message to 
the menu it will fill in the swp structure of the menu with its 
size. 

*/ 

SWP Swp; 

ULONG ulStyle; 

ulStyle = WinQueryWindowULong (hWndMenu,QWL_STYLE) & ~MS_ACTIONBAR 
WinSetWindowULong (hWndMenu,QWL_STYLE,ulStyle); 

WinQueryWindowPos(hWndMenu, (PSWP)&Swp); 

Swp.f1 = SWP_MOVE 1 SWP_SIZE; 

Swp.hwndlnsertBehind = HWND_T0P; 

/* Set owner to frame here so that WM_MEASUREITEM messages are 
sent to the frame window for processing -- in case menu is 
ownerdraw */ 

WinSetOwner (hWndMenu,hWndOwner); 

WinSendMsg(hWndMenu, WM_ADJUSTWINDOWPOS, (MPARAM)(PSWP)&Swp, NULL); 

WinPopupMenu (hWndOwner,hWndOwner,hWndMenu, 
bRight ? x : x - Swp.cx, y - Swp.cy, 0, 

PU_HCONSTRAIN | PU_VCONSTRAIN J PU_KEYBOARD | 

PU_M0USEBUTT0N1 J ulFlags); 
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return; 

} 

VOID SetMenuCheckMarks (HPS hps, HWND hWndMenu) 

{ 

hbmCheckl = GpiLoadBitmap (hps,0 3 IDBMP_CHECK1,0L,0L); 

hbmUnCheckl = GpiLoadBitmap (hps,0,IDBMPJJNCHECK1,0L,0L); 

hbmCheck2 = GpiLoadBitmap (hps,0,IDBMP_CHECK2,0L,0L); 

hbmUnCheck2 = GpiLoadBitmap (hps,0,IDBMP_UNCHECK2,0L,0L); 

/* Set the checkmarks for the horizontal alignment */ 
WinSetCheckMark (hWndMenu,IDM_ALIGNLEFT 3 hbmCheckl,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNLEFT,hbmUnCheckl 3 FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNCENTER,hbmCheckl,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNCENTER,hbmUnCheckl,FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNRIGHT,hbmCheckl,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNRIGHT,hbmUnCheckl,FALSE); 

/* Set the checkmarks for the vertical alignment */ 
WinSetCheckMark (hWndMenu,IDM_ALIGNTOP,hbmCheck2,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNTOP,hbmUnCheck2,FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNMIDDLE,hbmCheck2,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNMIDDLE,hbmUnCheck2,FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNBOTTOM,hbmCheck2,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNBOTTOM,hbmUnCheck2,FALSE); 
return; 


VOID SetOwnerDrawBitmapHandles (HPS hps, HWND hWndMenu) 

{ 

MENUITEM mi; 

USHORT usCnt; 

usCnt = LOUSHORT(WinSendMsg (hWndMenu, MM_GUERYITEMCOUNT, 0L, 0L)); 

while (usCnt) 

{ 

WinSendMsg (hWndMenu, MM_CUERYITEMBYPOS, 

MPFR0M2SH0RT (usCnt,0), MAKE_16BIT_P0INTER (&mi)); 

/* The menu item id is the same as the bitmap id */ 
mi.hltem = (ULONG)GpiLoadBitmap (hps,0,mi.id,0L,0L); 

WinSendMsg (hWndMenu, MM_SETITEMHANDLEBYPOS, 

MPFR0M2SH0RT (usCnt,0), (MPARAM)mi.hltem); 
usCnt- -; 

} 

return; 


MRESULT EXPENTRY ClientWndProc 

{ 


(HWND hWnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 
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BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

HPS hPS; 

switch (msg) 

{ 

case WM_CREATE: 

/* Retrieve the handle of the FID_MENU window */ 
hWndMenu = WinWindowFromID (WinQueryWindow(hWnd,QW_PARENT), 
FID_MENU); 

/* Load the color pop-up menu */ 

hColorMenu = WinLoadMenu (HWND_OBJECT 3 0 3 COLOR_MENU); 

hPS = WinGetPS (hWnd); 

/* Load and set the checkmark bitmaps */ 

SetMenuCheckMarks (hPS 3 hWndMenu); 

/* Load and set the owner draw bitmap handles */ 
SetOwnerDrawBitmapHandles (hPS,hColorMenu); 

WinReleasePS (hPS); 

/* Add the Edit menu item to the main menu */ 

AddEditMenuItem (hWndMenu); 

/* Add the Bitmap menu item to the main menu */ 

AddBitmapMenu (hWndMenu); 

/* Add the About menu item to the system menu */ 
AddAboutToSystemMenu (WinQueryWindow (hWnd, QW_PARENT)); 
break; 

case WM_DESTROY: 

/* Delete the bitmaps for the menu items */ 

GpiDeleteBitmap (hbmCheckl); 

GpiDeleteBitmap (hbmUnCheckl); 

GpiDeleteBitmap (hbmCheck2); 

GpiDeleteBitmap (hbmUnCheck2); 

WinDestroyWindow (hColorMenu); 
break; 

case WM_BUTTON1DOWN: 
bWindowColor = TRUE; 

WinLoadString (hab 3 0, IDS_WINDOWCOLOR 3 sizeof(szColor) 3 
szColor); 

WinSendMsg (hColorMenu,MM_SETITEMTEXTBYPOS, 

MPFROMSHORT(0),MAKE_16BIT_P0INTER(szColor)); 
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/* Call WinDefWindowProc so that window is activated */ 
mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 

PlacePopup (hWnd, hColorMenu, 

SH0RT1FROMMP(mpl),SH0RT2FR0MMP(mpl),FALSE, 

PUJMONE); /* Allow button to be released */ 
break; 

case WM_BUTT0N2D0WN: 
bWindowColor = FALSE; 

WinLoadString (hab, 0, IDS_TEXTCOLOR, sizeof(szColor), szColor); 
WinSendMsg (hColorMenu 3 MM_SETITEMTEXTBYPOS J 

MPFROMSHORT(0),MAKE_16BIT_P0INTER(szColor)); 

/* Call WinDefWindowProc so that window is activated */ 
mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 

PlacePopup (hWnd, hColorMenu, 

SH0RT1FROMMP(mpl),SH0RT2FR0MMP(mpl),TRUE, 
PUJ/I0USEBUTT0N2D0WN) ; 
break; 

case WM_COMMAND: 
case WM_SYSCOMMAND: 
switch (LOUSHORT(mpl)) 

{ 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

case IDM_STYLENORMAL: 
case IDM_STYLEUNDERSCORE: 
case IDM_STYLESTRIKEOUT: 

WinCheckMenuItem (hWndMenu, Style, FALSE); 

Style = LOUSHORT(mpl); 

WinCheckMenuItem (hWndMenu, L0USH0RT(mp1), TRUE); 

flCmd &= ~(DT_UNDERSCORE | DT_STRIKEOUT); 

flCmd |= StyleFlags[L0USH0RT(mp1) - IDM_STYLENORMAL]; 

WinlnvalidateRect (hWnd,NULL,FALSE); 

break; 

case IDM_ALIGNLEFT: 
case IDM_ALIGNCENTER: 
case IDM_ALIGNRIGHT: 

WinCheckMenuItem (hWndMenu, HAlign, FALSE); 

HAlign = LOUSHORT(mpl); 

WinCheckMenuItem (hWndMenu, L0USH0RT(mp1), TRUE); 
flCmd &= ~(DT_LEFT J DT_CENTER | DT_RIGHT); 
flCmd != AlignFlags[L0USH0RT(mp1) - IDM_ALIGNLEFT]; 
WinlnvalidateRect (hWnd,NULL,FALSE); 
break; 
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case IDM_ALIGNTOP: 
case IDM_ALIGNMIDDLE: 
case IDM_ALIGNBOTTOM: 

WinCheckMenuItem (hWndMenu, VAlign, FALSE); 

VAlign = L0USH0RT(mp1); 

WinCheckMenuItem (hWndMenu, L0USH0RT(mp1), TRUE); 
flCmd &= ~(DT_T0P | DT_VCENTER | DT_B0TT0M); 
flCmd j= AlignFlags[L0USH0RT(mp1) - IDM_ALIGNLEFT]; 
WinlnvalidateRect (hWnd,NULL,FALSE); 
break; 

case IDM_BMPITEM1: 
case IDM_BMPITEM2: 

{ 

USHORT usChecked; 

/* Toggle the checkmark flag */ 
usChecked = 

LOUSHORT(WinlsMenuItemChecked (hWndMenu, 

LOUSHORT(mpl))); 

usChecked A = MIA_CHECKED; 

WinCheckMenuItem (hWndMenu, L0USH0RT(mp1), usChecked); 
break; 


case IDBMP_0DITEM1: 
case IDBMP_0DITEM2: 
case IDBMP_0DITEM3: 

{ 

USHORT usChecked; 

/* Toggle the checkmark flag */ 
usChecked = 

LOUSHORT(WinlsMenuItemChecked (hColorMenu, 

LOUSHORT(mpl))); 

usChecked A = MIA_CHECKED; 

WinCheckMenuItem (hColorMenu, LOUSHORT(mpl), usChecked); 

/* Toggle the color field */ 
if (bWindowColor) 

lWindowColor A = lColorTablefLOUSHORT(mpl)-IDBMP_ODITEM1]; 
else 

ITextColor A = lColorTable[LOUSHORT(mp1)-IDBMP_0DITEM1]; 
WinlnvalidateRect (hWnd,NULL,FALSE); 
break; 


case SC_CL0SE: 

WinPostMsg (hWnd,WM_QUIT,0L,0L); 
break; 
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default: 

bHandled = (msg == WM_COMMAND); 

} 

break; 

case WMJVIEASUREITEM: 

MeasureOwnerltem ((P0WNERITEM)mp2); 
break; 

case WM_DRAWITEM: 

DrawOwnerltem ((P0WNERITEM)mp2); 
mReturn = (MRESULT)TRUE; 
break; 

case WM_INITMENU: 

if (SHORT1FROMMP(mpl) == IDM_EDIT) 

{ 

ULONG ulFormat; 

WinEnableMenuItem ((HWND)mp2, IDMJJNDO, bUndoAvailable); 
WinEnableMenuItem ((HWND)mp2, IDM_COPY, bSelected); 
WinEnableMenuItem ((HWND)mp2, IDM_CUT, bSelected); 
WinEnableMenuItem ((HWND)mp2, IDM_PASTE, 
WinQueryClipbrdFmtlnfo (hab, CF_TEXT, &ulFormat)); 

} 

else if ((HWND)mp2 == hColorMenu) 

{ 

USHORT Pos; 

for (Pos = 0; Pos < 3; Pos++) 

WinSendMsg (hColorMenu, MM_SETITEMATTRBYPOS, 

MPFR0M2SH0RT(Pos+1,0), 

MPFR0M2SH0RT(MIA_CHECKED, 
bWindowColor ? 

((lWindowColor & lColorTable[Pos]) ? MIA_CHECKED : 0) 

((ITextColor & lColorTable[Pos]) ? MIA_CHECKED : 0))); 

} 

break; 

case WM_PAINT: 

hPS = WinBeginPaint (hWnd,0,0); 

{ 

RECTL Recti; 

GpiCreateLogColorTable (hPS,LCOL_RESET,LCOLF_RGB,0L,0L,NULL); 
WinQueryWindowRect (hWnd, &Rectl); 

WinFillRect (hPS, &Rectl, lWindowColor); 

WinDrawText (hPS,-1L, szText, &Rectl, 

ITextColor, lWindowColor, flCmd); 

} 

WinEndPaint (hPS); 
break; 
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case WM_ERASEBACKGROUND: 
mReturn = (MRESULT)1; 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


MENU.H 


/* 


Menu Header File 
Chapter 5 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define 

ID_APPNAME 

1 

#define 

IDS WINDOWCOLOR 

2 

#define 

IDS_TEXTCOLOR 

3 

#define 

IDBMP_CHECK1 

50 

#define 

IDBMP UNCHECK1 

51 

#define 

IDBMP CHECK2 

52 

#define 

IDBMP_UNCHECK2 

53 

#define 

IDBMP_BMPITEM1 

54 

#define 

IDBMP_BMPITEM2 

55 

#define 

IDBMP_0DITEM1 

56 

#define 

IDBMP_0DITEM2 

57 

#define 

IDBMP_0DITEM3 

58 

#define 

o 

o 

i— 

o 

JD 

1 

m 

z 

c= 

100 

#define 

IDC_C0L0R 

101 

#define 

IDM_ALIGN 

400 

#define 

IDM ALIGNLEFT 

401 

#define 

IDM ALIGNCENTER 

402 

#define 

IDM_ALIGNRIGHT 

403 

#define 

IDM_ALIGNTOP 

404 

#define 

IDM_ALIGNMIDDLE 

405 

#define 

IDM ALIGNBOTTOM 

406 
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#define IDM_STYLE 500 
#define IDM_STYLENORMAL 501 
#define IDM_STYLEUNDERSCORE 502 
#define IDM_STYLESTRIKEOUT 503 

#define IDM_EDIT 600 
#define IDMJJNDO 601 
#define IDM_C0PY 602 
#define IDM_CUT 603 
#define IDM_PASTE 604 

#define IDM_ABOUT 700 

#define BITMAP_MENU 800 
#define IDMJ3MPITEM1 801 
#define IDM_BMPITEM2 802 


MENUXTRA.H 


The following is the code for the MENUXTRA.H header file. We could have simply 
included this code in the file MENU.H. However, we have broken it out here so that 
you may use it in your own applications if you desire. It contains undocumented menu 
messages and macros. 


/* 


Undocumented PM Menu Messages Header File 
Chapter 5 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define WM_MENUCHAR 0x003f 

#define MM_SELECTITEMBYPOS 0x019e 

#define MMJ/IATCHMNEMONIC 0x01 f0 

#define MM_DELETEITEMBYPOS 0x01 fl 

#define MM_REMOVEITEMBYPOS 0x01f2 

#define MM_QUERYITEMBYPOS 0x01 f 3 

#define MM_SETITEMBYPOS 0x01 f4 

#define MM_QUERYITEMATTRBYPOS 0x01f5 

#define MM_SETITEMATTRBYPOS 0X01 f 6 

#define MM_QUERYITEMTEXTBYPOS 0x01 f7 

#define MM_QUERYITEMTEXTLENGTHBYPOS 0X01 f 8 
#define MM_SETITEMTEXTBYPOS 0X01 f9 

#define MM_SETITEMHANDLEBYPOS 0x01 fa 

#define MM_PORTHOLEINIT 0x01fb 

#define MM_SETITEMCHECKMARKBYPOS 0x01 fc 
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#define MM_SETITEMCHECKMARK 0x0210 

#define WM_MENUHELP 0x0433 

#define WinSetCheckMark(hWndMenu, id, hbm, bcheck) \ 

((BOOL)WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, \ 
MPFR0M2SH0RT(id, (USHORT)bcheck), (MPARAM)hbm)) 

#define WinSetCheckMarkByPos(hWndMenu, id, hbm, bcheck) \ 

((BOOL)WinSendMsg(hWndMenu,MM_SETITEMCHECKMARKBYPOS, \ 
MPFR0M2SH0RT(id, (USHORT)bcheck), (MPARAM)hbm)) 

#define MAKE_16BIT_P0INTER(p) \ 

((PVOID)MAKEULONG(LOUSHORT(p),(HXUSHORT(p) « 3) | 7)) 


MENU.RC 


/* 


Menu Resource File 
Chapter 5 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 
#include "menu.h 


ICON ID APPNAME MENU.ICO 


/* Checkmark bitmaps */ 
BITMAP IDBMP_CHECK1 
BITMAP IDBMPJJNCHECK1 
BITMAP IDBMP_CHECK2 
BITMAP IDBMP_UNCHECK2 


"CHECK1 .BMP" 
"UNCHECK1.BMP" 
"CHECK2.BMP" 
"UNCHECK2.BMP" 


/* Bitmap menu item bitmaps */ 

BITMAP IDBMP_BMPITEM1 "BMPITEM1.BMP" 
BITMAP IDBMP BMPITEM2 "BMPITEM2.BMP" 


/* Ownerdraw bitmaps 
BITMAP IDBMP_0DITEM1 
BITMAP IDBMP_0DITEM2 
BITMAP IDBMP 0DITEM3 


" 0DRED.BMP" 
"ODGREEN.BMP 
"ODBLUE. BMP 11 


STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Menu Application 

IDS WINDOWCOLOR "Window Color" 
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IDS_TEXTCOLOR "Text Color" 

END 


MENU ID APPNAME 


{ 


} 


SUBMENU "-Style", 

{ 

MENUITEM "-Normal", 
MENUITEM "-Underscore", 
MENUITEM "-Strikeout", 

} 


IDM_STYLE 

IDM_STYLENORMAL, 0, MIA_CHECKED 
IDM_STYLEUNDERSCORE 
IDM STYLESTRIKEOUT 


SUBMENU "-Alignment", IDM_ALIGN, MIS_TEXT 


MENUITEM 

"Horizontal", 





MIS_ 

STATIC, MIA FRAMED 




MENUITEM 

" -Left", 

IDM_ALIGNLEFT, 




MENUITEM 

" -Center", 

IDM_ALIGNCENTER, 

0, 

MIA_ 

CHECKED 

MENUITEM 

" -Right", 

IDM_ALIGNRIGHT, 




MENUITEM 

"Vertical", 

-1, 




MIS_ 

BREAKSEPARATOR 

| MIS_STATIC, MIA_ 

FRAMED 


MENUITEM 

" -Top", 

IDM_ALIGNTOP, 




MENUITEM 

" -Middle", 

IDM ALIGNMIDDLE, 

0, 

MIA_ 

CHECKED 

MENUITEM 

" -Bottom", 

IDM_ALIGNBOTTOM, 





MENU COLORJ/IENU 

{ 

MENUITEM "", IDC_COLOR, MIS_STATIC 
MENUITEM "", IDBMP_ODITEM1, MIS_OWNERDRAW 
MENUITEM "", IDBMP_0DITEM2, MIS_OWNERDRAW 
MENUITEM "", IDBMP_0DITEM3, MIS_OWNERDRAW 

} 


MIS_BREAK 
MIS_BREAK 
MIS BREAK 


MENU BITMAP_MENU 

{ 

MENUITEM "#54", IDM_BMPITEM1, MIS_BITMAP 
MENUITEM "#55", IDM_BMPITEM2, MIS_BITMAP 

} 


rcinclude ..\common\about.dig 


MENU.DEF 


NAME 

DESCRIPTION 
PROTMODE 
HEAPSIZE 
STACKSIZE 


MENU WINDOWAPI 

'Menu Program (c) 1933 Blain, Delimon, & English 

4096 

16384 
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EXPORTS ClientWndProc 

AboutDlgProc 


Using the Menu Application 

Using the Menu application is fairly self explanatory. After you have opened the pro¬ 
gram, you will see the Menu Application main window. Spend some time clicking the 
various menu choices and noting their effect on the displayed text. Take some time to 
note how the special checkmarks work. Figure 5.3 shows the Alignment pull-down menu, 
which uses the special checkmarks. 


Figure 53. 
Use of special 
checkmarks. 


f. Edit Style [ Alignment Bi t maps 

| Honiontal | VerticaTl 




p Left . : U' lop 
p Center \~* Middle 


Right 


Bottom 




Meno Text String 


Clicking in the client area with the left mouse button will bring up a menu that en¬ 
ables you to change the color of the client area. The color for the client area is deter¬ 
mined by a combination of the colors designated by buttons that are pressed. Notice that 
the pop-up menu remains open when you release the left mouse button. 

Clicking with the right mouse button will open a pop-up menu that acts differently 
from the menu brought up with the left mouse button. The color for the text is set with 
the buttons in this pop-up menu in a way similar to setting text color for the client 
area. Ffowever, note that when you release the right mouse button, the pop-up menu 
disappears. 
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Basic Menu and Changing Menu Items 

There are two ways to create a menu for use in your application: Load the menu from the 
resource file or dynamically build it in the code. We will do both here, but let’s begin 
with a simple menu for our application that will be defined in the resource file. We begin 
with a main menu in our application with one menu item called “Style.” This menu item 
will contain a submenu with three choices. 

MENU ID_APPNAME 

{ 

SUBMENU "-Style", IDM_STYLE 

{ 

MENUITEM "-Normal", IDM_STYLENORMAL, 0, MIA_CHECKED 

MENUITEM "-'Underscore", IDM_STYLEUNDERSCORE 

MENUITEM "-Strikeout", IDM_STYLESTRIKEOUT 

} 

} 

The first line gives our menu an identifier of IDD_APPNAME. We identify our first menu 
item as a submenu with the SUBMENU keyword, and it will be a text item (default) with an 
identifer of IDM_STYLE. Below the submenu, we list the three menu items that will ap¬ 
pear in the pull-down menu. Notice that the first item will be checked initially as we 
have set the initial attribute to MIA_CHECKED. 

Since this will be our actionbar menu, we want this menu to be set as the FID_MENU 
menu for our main window. This is done by using the FCF_MENU frame control flag when 
we create the main window. Using this flag tells PM to look for a menu resource with the 
identifier specified and load it as the main menu: 

ULONG flFrameFlags = FCF_TITLEBAR J FCF_SYSMENU | FCF_SIZEBORDER ] 

FCF_MINMAX | FCF_SHELLPOSITION | FCF_TASKLIST | 
FCF_MENU | FCF_ICON; 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

Alternatively, we could leave the FCF_MENU flag off of the frame control flags and add 
the menu later with a call to Win Load Menu. 

Now that we have the basis for our menu, we can begin to add new menu items to 
our menu. Let’s add an “Edit” menu item as the first item in the menu. We will want to 
include menu options for “Undo,” “Copy,” “Cut,” and “Paste.” The first step in dynami¬ 
cally creating a new menu is to create a menu handle: 

hWndEditMenu = WinCreateMenu (HWND_OBJECT, NULL); 
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WinCreateMenu will create a window of class WC_MENU. Passing NULL for the menu 
template will create a menu window with no menu items. The ID for this menu window 
will be FID_MENU. So as not to cause confusion with the main menu window, we will 
rename it to IDM_EDIT: 

WinSetWindowUShort (hWndEditMenu, QWS_ID, IDM_EDIT); 

The style of this menu window is also MS_ACTIONBAR | WS_CLIPSIBLINGS | 
MS_ROOT. 


Note: Although this is not the style for a submenu, PM will change the style to 
MIS_SUBMENU J WS_SAVEBITS j WS_CLIPSIBLINGS when the menu is inserted 
into the main menu. 


We are now ready to begin adding the menu items to this menu. To add the items, 
we need to fill in the MENUITEM structure and send the MM_INSERTITEM message. We will 
initially want all of the menu items to be disabled: 

MENUITEM mi; 

hWndEditMenu = WinCreateMenu (HWND_OBJECT, NULL); 

WinSetWindowUShort (hWndEditMenu, QWS_ID, IDM_EDIT); 

mi.iPosition = MIT_END; 

mi.afStyle = MIS_TEXT; 

mi.atAttribute = MIA_DISABLED; 

mi.id = IDMJJNDO; 

mi.hwndSubMenu = 0; 

mi.hltem = 0; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Undo"); 
mi.id = IDM_COPY; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Copy"); 
mi.id = IDM_CUT; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "Cu~t"); 
mi.id = IDM_PASTE; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, "-Paste"); 


Let’s insert a separator between the Undo and Copy menu items: 

mi.iPosition = 1; 

mi.afStyle = MIS_SEPARATOR; 

mi.afAttribute = 0; 

mi.id = -1; 

WinSendMsg (hWndEditMenu, MM_INSERTITEM, &mi, ""); 
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Now that the submenu is constructed, we can add it to the main menu as the first 
item in the menu: 

mi.iPosition = 0; 

mi.afStyle = MIS_TEXT | MIS_SUBMENU; 

mi.afAttribute = 0; 

mi.id = IDM_EDIT; 

mi.hwndSubMenu = hWndEditMenu; 

WinSendMsg (hWndMenu, MM_INSERTITEM, &mi, "-Edit"); 


Figure 5.4 shows what this submenu looks like after inserting the edit menu item to 
the top-level menu. 


Figure 5.4. 

Dynamically added Edit 
submenu. 



Another way to add a submenu is to define it separately in the RC file, load it, and 
use that as the submenu handle in the menuitem structure. An example of this follows in 
the section on bitmap menu items. 

With the edit menu in place, we will want to enable the menu items as appropriate. 
For example, we will want to enable the paste option if there is any data in the clipboard. 
Because we really only care about the clipboard when the submenu is about to be dis¬ 
played, we can use the WM_INITMENU message to tell us the menu is about to be displayed 
and query the clipboard at that time. 

case WM_INITMENU: 

if (SHORT1FROMMP(mpl) == IDM_EDIT) 

{ 
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ULONG ulFormat; 

WinEnableMenuItem ((HWND)mp2, IDMJJNDO, bUndoAvailable); 

WinEnableMenuItem ((HWND)mp2, IDM_C0PY, bSelected); 

WinEnableMenuItem ((HWND)mp2, IDM_CUT, bSelected); 

WinEnableMenuItem ((HWND)mp2, IDM_PASTE, 

WinQueryClipbrdFmtlnfo (hab, CF_TEXT, &ulFormat)); 

} 

To test this, start the menu application and select the “Edit” option. Notice that all 
the menu options are disabled. Now start the system editor and enter some text. Select 
the text and select the “Edit,” and then the “Copy” options in the system editor. Now 
select the “Edit” option in the menu application. Notice that the “Paste” option is now 
enabled because there is data in the clipboard with the format CF_TEXT. 

In our application, bSelected and bUndoAvailable are always set to FALSE, but 
would normally change during the course of the application. 


Changing the Menu Item Checkmark 

When a menu item has the MIA_CHECKED attribute, the system draws a default checkmark 
to the left of the menu item. This checkmark is shown in Figure 5.5. 


Figure 5.5. 

A menu item marked 
with the default 
checkmark. 



Edit [ Style Alignm ent Bitmaps 


| Normal j 
^/Underscore [ 
Strikeout j 


[Menu Text String 




In earlier versions of OS/2, if you did not want to use the system default checkmark, 
you had to define the menu item as a MISJDWNERDRAW item and draw the entire menu 
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item with a new checkmark. One of the newer undocumented features of OS/2 2.1 is 
the capability to change the checkmark that is used for each menu item. This is accom¬ 
plished by sending a message to set both the bitmap used for the checked state and the 
bitmap used for the unchecked state. Two undocumented messages are provided here: 

MM_SETITEMCHECKMARK 0X0210 

mpl = MPFR0M2SH0RT (menuitemID,bchecked) 
menuitemID = ID of the menu item to set 
bchecked = TRUE if bitmap is for the checked state 

FALSE if bitmap is for the unchecked state 
mp2 = bitmap handle 

MM_SETITEMCHECKMARKBYPOS 0X01FC 

mpl = MPFR0M2SH0RT (position,bchecked) 

position = Position of menu item to set 
bchecked = TRUE if bitmap is for the checked state 

FALSE if bitmap is for the unchecked state 
mp2 = bitmap handle 

The checkmarks must be set for each menu item that we want to have using the new 
checkmarks. For example, if we have loaded two bitmaps and want to set them for menu 
items IDM_ALIGNLEFT and IDM_ALIGNCENTER, we would have to send four messages. If 
hbmUnchecked is our bitmap for the unchecked state and hbmChecked is our bitmap for 
the checked state, we would send the following messages: 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (IDM_ALIGNLEFT,FALSE), hbmUnchecked); 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (IDM_ALIGNLEFT,TRUE), hbmChecked); 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (IDM_ALIGNCENTER,FALSE), hbmUnchecked); 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (IDM_ALIGNCENTER,TRUE), hbmChecked); 

It is not required to set both the checked and unchecked bitmaps. If you only set the 
bitmap for the unchecked state the system will use the default bitmap for the checked 
state. 

What dimensions do we use for the checkmark bitmap? When the checkmark is drawn 
to the left of the menu item, PM will only display the portion of the bitmap that fits the 
size of the default checkmark bitmap. PM does not stretch or shrink the bitmap to fit. 
The default checkmark is identified by SBMP_MENUCHECK, so all that is needed is to query 
its dimensions. This can be done with the following code: 

BITMAPINFOHEADER bmlnfoSystem; 

HBITMAP hbmCheckMark = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUCHECK); 
GpiQueryBitmapParameters (hbmCheckMark,&bmInfoSystem); 

GpiDeleteBitmap (hbmCheckMark); 
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The bitmap width is in bmlnfoSystem.cx and its height in bmlnfoSystem.cy. After 
loading your checkmark bitmap, it is necessary to create a bitmap of the same size as the 
system checkmark. The function FitCheckMarkToSystem will take a checkmark bitmap 
handle and return a handle of a bitmap sized to fit the system checkmark: 

HBITMAP FitCheckMarkToSystem (HBITMAP hbmMyCheckMark) 

{ 

BITMAPINFOHEADER bmlnfoSystem, 
bmlnfoMine; 

HBITMAP hbmCheckMark; 

/* Query the system checkmark bitmap size */ 
hbmCheckMark = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUCHECK); 
GpiQueryBitmapParameters (hbmCheckMark,&bmlnfoSystem); 
GpiDeleteBitmap (hbmCheckMark); 

/* Query our checkmark bitmap size */ 

GpiQueryBitmapParameters (hbmMyCheckMark,&bmInfoMine); 

/* Determine if bitmap needs to be resized */ 
if ( (bmlnfoMine.cx != bmlnfoSystem.cx) |] 

(bmlnfoMine.cy != bmlnfoSystem.cy) ) 

{ 

HDC hdcMem; 

HPS hpsMem; 

SIZEL Sizl; 

RECTL RectlSrc, 

RectlTgt; 

HBITMAP hbmNewCheckMark; 

/* Create a destination memory DC */ 

hdcMem = DevOpenDC (hab, 0D_MEM0RY, ,, * M , 0, NULL, (HDC) NULL); 

/* Create a destination memory PS */ 

Sizl.cx = Sizl.cy = 0L; 

hpsMem = GpiCreatePS (hab,hdcMem,&Sizl, 

PU_PELS | GPIF_DEFAULT | GPIT_NORMAL j GPIA_ASSOC); 

/* Create the new bitmap */ 

hbmNewCheckMark = GpiCreateBitmap (hpsMem, &bmInfoSystem, 0L, 
NULL, NULL); 

/* Set the bitmaps into the memory PS */ 

GpiSetBitmap (hpsMem, hbmNewCheckMark); 

/* Stretch/Shrink the bitmap */ 

/* Target x,y coordinates */ 

RectlTgt.xLeft = RectlTgt.yBottom = 0L; 
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/* Target width and height */ 

RectlTgt.xRight = bmlnfoSystem.cx; 

RectlTgt.yTop = bmlnfoSystem.cy; 

WinDrawBitmap (hpsMem, hbmCheckMark, NULL, (PPOINTL)&RectlTgt, 
0L, 0L, DBM_STRETCH); 

/* Cleanup */ 

GpiSetBitmap (hpsMem, NULL); 

GpiAssociate (hpsMem, NULL); 

GpiDestroyPS (hpsMem); 

DevCloseDC (hdcMem); 

/* Destroy the original bitmap and set return bitmap handle */ 
GpiDeleteBitmap (hbmMyCheckMark); 
hbmMyCheckMark = hbmNewCheckMark; 

} 

return (hbmMyCheckMark); 


It is only necessary to resize the checkmark bitmap if it was not originally created the 
same size as the system default checkmark. Typically, this is a width of 14 and a height of 


10 . 


Returning to our program, we have defined another menu item in our resource file 
to set the alignment of text: 


SUBMENU "-Alignment", IDM_ALIGN, MIS_TEXT 

{ 


MENUITEM "Horizontal", -1, 

MIS_STATIC, MIA_FRAMED 
MENUITEM " -Left", IDM_ALIGNLEFT, 

MENUITEM " -Center", IDM_ALIGNCENTER, 0, MIA_CHECKED 

MENUITEM " -Right", IDM__ALIGNRIGHT, 

MENUITEM "Vertical", -1, 

MIS_BREAKSEPARATOR j MIS_STATIC, MIA_FRAMED 
MENUITEM " -Top", IDM_ALIGNTOP, 

MENUITEM " -Middle", IDM_ALIGNMIDDLE, 0, MIA_CHECKED 

MENUITEM " -Bottom", IDM_ALIGNBOTTOM, 


This submenu has two columns of selections, one for horizontal and one for vertical 
alignment. The first item in each column is a MIS_STATIC item, which acts as a column 
header and cannot be selected. The MIA_FRAMED attribute causes a line to be drawn un¬ 
derneath the item. The MIS_BREAKSEPARATOR style causes a new column to begin with 
the Vertical menu item. We have gone ahead and set the initial alignment attributes by 
setting the MIA_CHECKED attribute for the third item in each column. To demonstrate 
the setting of a different checkmark bitmap, we will use two bitmaps for the first col¬ 
umn and two different bitmaps for the second column. These are shown in Figures 5.6 
through 5.9. 
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Figure 5.6. 

Image of 
IDBMP_CHECK1 
checkmark image. 


Figure 5.7. 

Image of 

IDBMP_UNCHECK1 

checkmark image. 
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IDBMP_ CHECK2 
checkmark image. 
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Figure 5.9. 

Image of 

IDBMP_ UNCHECK2 
checkmark image. 



We use the WinSetCheckMark macro defined in the MENUXTRA.H file to set the 
checkmarks for each item in this submenu (see Figures 5.6 through 5.9). The bitmaps 
are set while processing the WM_CREATE message for the main window. Our bitmaps have 
been created with a width of 14 and a height of 10 so there is no need to call the 
FitCheckMarkToSystem function to resize them: 

#define WinSetCheckMark(hWndMenu, id, hbm, bcheck) \ 

((BOOL)WinSendMsg(hWndMenu,MM_SETITEMCHECKMARK, \ 

MPFR0M2SH0RT(id, (USHORT)bcheck), hbm)) 


VOID SetMenuCheckMarks (HPS hps, HWND hWndMenu) 

{ 

hbmCheckl = GpiLoadBitmap (hps,0,IDBMP_CHECK1,0L,0L); 
hbmUnCheckl = GpiLoadBitmap (hps,0,IDBMPJJNCHECK1,0L,0L); 
hbmCheck2 = GpiLoadBitmap (hps,0,IDBMP_CHECK2,0L,0L); 
hbmUnCheck2 = GpiLoadBitmap (hps,0,IDBMP_UI\JCHECK2,0L, 0L); 


/* Set the checkmarks for the horizontal alignment */ 
WinSetCheckMark (hWndMenu,IDM_ALIGNLEFT,hbmCheckl,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNLEFT,hbmUnCheckl,FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNCENTER,hbmCheckl,TRUE ); 
WinSetCheckMark (hWndMenu,IDM_ALIGNCENTER,hbmUnCheckl,FALSE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNRIGHT,hbmCheckl,TRUE); 
WinSetCheckMark (hWndMenu,IDM_ALIGNRIGHT,hbmUnCheckl,FALSE); 


/* Set the checkmarks for the 


WinSetCheckMark 

WinSetCheckMark 

WinSetCheckMark 

WinSetCheckMark 

WinSetCheckMark 


(hWndMenu, IDM_ 
(hWndMenu, IDM_ 
(hWndMenu, IDM~ 
(hWndMenu,IDM_ 
(hWndMenu,IDM_ 


vertical alignment */ 

ALIGNTOP,hbmCheck2,TRUE); 
.ALIGNTOP,hbmUnCheck2,FALSE); 
ALIGNMIDDLE,hbmCheck2,TRUE); 
ALIGNMIDDLE,hbmUnCheck2,FALSE); 
ALIGNBOTTOM,hbmCheck2,TRUE) ; 
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WinSetCheckMark (hWndMenu,IDM_ALIGNBOTTOM,hbmUnCheck2,FALSE); 
return; 

} 


SetMenuCheckMarks is called during the WM_CREATE message processing for the 
application’s main window: 

case WM_CREATE: 

/* Retrieve the handle of the FID_MENU window */ 
hWndMenu = WinWindowFromID (WinQueryWindow(hWnd,QW_PARENT), 
FID_MENU); 


hPS = WinGetPS (hWnd); 

/* Load and set the checkmark bitmaps */ 
SetMenuCheckMarks (hPS, hWndMenu); 


break; 


Bitmap Menu Items 

So far we have dealt only with the MIS_TEXT menu style as the type of item to display. 
We can also have MIS_BITMAP and MIS_OWNERDRAW menu styles. Let’s take a quick look 
at the MIS_BITMAP menu style. This style defines a bitmap handle to display in the menu 
item instead of text. The size of the menu item is adjusted by PM to contain the bitmap. 
The bitmap is displayed similarly to a text item; space is reserved to the left of the 
menu item for the checkmark, and space is reserved to the right for the submenu 
indicator. 

We have defined a menu in the resource file called BITMAP_MENU that contains two 
menu items defined with the MIS_BITMAP style. We will add this menu as the last menu 
item in the main menu (see Figure 5.10). 

#define IDBMP_BMPITEM1 54 

#define IDBMP BMPITEM2 55 


BITMAP IDBMP_BMPITEM1 "BMPITEM1.BMP" 

BITMAP IDBMP_BMPITEM2 "BMPITEM2.BMP" 

MENU BITMAP_MENU 

{ 

MENUITEM "#54", IDM_BMPITEM1, MIS_BITMAP 
MENUITEM 11 #55" , IDM_BMPITEM2, MIS_BITMAP 



} 
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When a bitmap menu item is defined in the resource file, the text for the item is a 
string representation of the bitmap identifier. This string is the # character followed by 
the identifier: 

VOID AddBitmapMenu (HWND hWndMenu) 

{ 

MENUITEM mi; 

mi.iPosition = MIT_END; 

mi.atStyle = MIS_TEXT j MIS_SUBMENU; 

mi.afAttribute = 0; 

mi. id = BITMAPJV1ENU; 

mi.hwndSubMenu = WinLoadMenu (HWND_OBJECT,0,BITMAP_MENU); 
mi.hltem = NULL; 

WinSendMsg (hWndMenu, MM_INSERTITEM, &mi, "Bitmaps"); 
return; 

} 


Figure 5.10. 

A bitmap item selected 
with a checkmark. 



To see what the bitmap item looks like with a checkmark (Figure 5.10), we will toggle 
the checkmark attribute when the WM_COMMAND message is received for either of the two 
menu items. 

case IDM_BMPITEM1: 
case IDM_BMPITEM2: 

{ 

USHORT usChecked; 
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/* Toggle to checkmark flag */ 
usChecked = 

LOUSHORT(WinlsMenuItemChecked (hWndMenu, L0USH0RT(mp1))); 
usChecked A = MIA_CHECKED; 

WinCheckMenuItem (hWndMenu, L0USH0RT(mp1), usChecked); 
break; 

} 

It is also possible to define a bitmap menu item for the actionbar. The definition of 
the menu item is the same as for any other item. When a menu window is destroyed, PM 
will delete bitmaps that we loaded implicitly by PM. These bitmaps are those specified 
for menu items in the resoure file. Bitmaps loaded by the application and set in menu 
items must be deleted by the application. 

OWNERDRAW Menu Items 

Now we move on to an interesting aspect of menus, the MIS_OWNERDRAW menu item style. 
This style enables you to customize the appearance of your menu items because the ap¬ 
plication draws the menu item. We are going to create a pop-up menu with three 
ownerdraw menu items and draw each menu item in the appropriate state as requested. 

When a MIS_OWNERDRAW item is to be displayed, the menu window sends a 
WM_MEASUREITEM to its owner window. This message gets passed up the menu chain until 
it reaches a frame window, which in turn sends it to the client window. The 
WMJVIEASUREITEM is sent whenever the size of the menu needs to be determined and is 
used to retrieve the width and height of the item. This is used in calculating the entire 
size of the menu window. The width that is returned will be added to by PM to include 
the width of both the SBMP_MENUCHECK and the SBMPJVIE NU ATT ACHED bitmaps. The 
SBMP_MENUATTACHED bitmap is the arrow that is normally seen to the right of the menu 
item when the menu item includes a submenu. 

If your menu items do not include submenus or you want to draw your own menu 
attached pointer, subtract the width of the SBMP_MENUATT ACHED bitmap. In our case, our 
menu items will be bitmaps, including a separate bitmap for the checked state, and do 
not include submenus. 

Whenever the menu item is to be drawn, aWM_DRAWITEM message is sent to its owner 
in the same way the WM_MEASUREITEM is sent. This message is sent when the item must 
be completely drawn, when the highlight state changes, or when the checkmark state 
changes. The application uses information passed in this structure to determine what state 
the menu item is in and draws the item appropriately. 

Both these messages pass a pointer to an OWNER ITEM structure: 
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typedef : 

struct _OWNERITEM 

{ /* 

oi */ 

HWND 

hwnd; 

/* 

Window handle of menu containing menu 
item */ 

HPS 

hps; 

/* 

HPS to draw into */ 

ULONG 

fsState; 

/* 

Style of the menu item */ 

ULONG 

fsAttribute; 

/* 

New attribute of menu item */ 

ULONG 

fsStateOld; 

/* 

Style of the menu item */ 

ULONG 

fsAttributeOld; 

/* 

Old attribute of menu item */ 

RECTL 

rclltem; 

/* 

Rectangle to draw into */ 

LONG 

idltem; 

/* 

ID of menu item to draw */ 

ULONG hltem; 

} OWNERITEM; 

/* 

Handle of item for menu item */ 


The WM_MEASUREITEM passes the following information: 

WMJVIEASUREITEM 0X0037 

mpl = SH0RT1FROMMP(mpl) Identifier of the menu window 

mp2 = (POWNERITEM) Pointer to an owneritem structure to be filled in 

The return value is ignored by the menu system in PM. 

The client window procedure processes this message by filling in the relit em. xRight 
and rclItem.yTop fields with the width and height of the item. Because we will be 
using bitmaps in our ownerdraw menu items, the width and height are set to the size 
of the bitmap: 

case WM_MEASUREITEM: 

MeasureOwnerltem ((P0WNERITEM)mp2); 
break; 

VOID MeasureOwnerltem (POWNERITEM poi) 

{ 

BITMAPINFOHEADER bmlnfoMenuAttached, 
bmlnfoMenuCheck, 
bmlnfoMenu; 

HBITMAP hbm = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUATTACHED); 
GpiQueryBitmapParameters (hbm,&bmlnfoMenuAttached); 

GpiDeleteBitmap (hbm); 

hbm = WinGetSysBitmap (HWND_DESKTOP,SBMP_MENUCHECK); 
GpiQueryBitmapParameters (hbm,&bmInfoMenuCheck); 

GpiDeleteBitmap (hbm); 

GpiQueryBitmapParameters ((HBITMAP)poi->hItem,&bmInfoMenu); 
poi->rclItem.xRight = (bmlnfoMenu.cx / 4) - 

bmlnfoMenuAttached.cx - bmlnfoMenuCheck.cx; 
poi->rclItem.yTop = bmlnfoMenu.cy; 
return; 


Note that for the width of our menu item, we have subtracted the width of the 
SBMP_MENUATTACHED and SBMP_MENUCHECK bitmaps because we will draw everything 
ourselves, and we want the rectangle used in the WM_OWNERDRAW message to match the 
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width of the bitmap. Remember that PM adds these widths back to our returned value 
so that the net result is that the resulting width of the menu item is the width of our 
bitmap. 

The WM_DRAWITEM message passes the following information: 

WM_DRAWITEM 0X0036 

mpl = SH0RT1FR0MMP(mp1) Identifier of the menu window 

mp2 = (POWNERITEM) Pointer to an owneritem structure to be filled in 

The return value is ignored by the menu system in PM. 

Determination of what state to draw the menu item is done by looking at the 
f sAttribute field of the OWNERITEM structure. You can ignore the f sState and 
f sStateOld fields as they simply contain the menu item style. After drawing the menu 
item, you must tell PM if it should perform the default processing for the current 
attributes. 

If you draw your own menu checkmarks or you do not use any, clear the MIA_CHECKED 
attribute of both the f sAttribute and f sAttributeOld fields, likewise for the 
MIA_HILITED and MIA_FRAMED attributes. For example, if you draw a menu item and 
the MIA_CHECKED attribute is set and you want the default checkmark drawn, leave the 
MIA_CHECKED attribute alone. On the other hand, if you do not want the system to draw 
the default checkmark, clear the MIA_CHECKED attribute in the OWNERITEM structure. You 
can use the following code: 

((P0WNERITEM)mp2)->fsAttribute = 

( ((P0WNERITEM)mp2)->fsAttributeOld &= ~MIA_CHECKED ); 

The MENU sample application shows a pop-up menu with three menu items. The pop¬ 
up menu is shown with each item aligned horizontally (see Figure 5.11). In order to show 
the six different states of a menu item, use a single bitmap with four different states 
already drawn in the bitmap. The offset of the portion of the bitmap to display is 
calculated in the DrawOwnerltem function called during the WM_DRAWITEM message 
processing. 

We will only draw that portion of the bitmap that shows the current state. The 
UNHILITED and HILITED bitmap portions will also be used to show the disabled state— 
they will be drawn with the DBM_HALFTONE ROP code. 

In defining our menus, we will use the hltem field of the MENU ITEM to contain the 
bitmap handle for the menu item. This is set for each menu item after the menu has been 
loaded. 

VOID SetOwnerDrawBitmapHandles (HPS hps, HWND hWndMenu) 

{ 

MENUITEM mi; 

USHORT usCnt; 
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usCnt = LOUSHORT(WinSendMsg (hWndMenu, MM_QUERYITEMCOUNT , 0L 3 0L)); 

while (usCnt) 

{ 

WinSendMsg (hWndMenu, MM_QUERYITEMBYPOS , 

MPFR0M2SH0RT (usCnt 3 0) 3 MAKE_16BIT_P0INTER (&mi)); 

/* The menu item id is the same as the bitmap id */ 
mi.hltem = (ULONG)GpiLoadBitmap (hps 3 0,mi.id 3 0L 3 0L); 

WinSendMsg (hWndMenu, MM_SETITEMHANDLEBYPOS 3 
MPFR0M2SH0RT (usCnt 3 0), (MPARAM)mi.hltem); 
usCnt- -; 

} 

return; 


Figure 5.11. 

Pop-up menu with 
owner-draw menu items. 



We will draw the appropriate bitmap into the hps when we receive the WM_DRAWITEM 
message: 

case WM_DRAWITEM: 

DrawOwnerltem ((P0WNERITEM)mp2); 
mReturn = (MRESULT)TRUE; 
break; 

VOID DrawOwnerltem (POWNERITEM poi) 

{ 


ULONG 

RECTL 


yOffset; 
Recti; 
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BITMAPINFOHEADER bmlnfoOwnerDraw; 

ULONG ropCode; 

/* Get the bitmap handle for the bitmap */ 

GpiQueryBitmapParameters ((HBITMAP)poi->hItem,&bmInfoOwnerDraw); 

/* Determine the offset of the portion of the bitmap to draw */ 
if (poi->fsAttribute & MIA_CHECKED) 
yOffset = bmlnfoOwnerDraw.cx / 2; 
else 

yOffset = 0; 

if (poi->fsAttribute & MIA_HILITED) 
yOffset += bmlnfoOwnerDraw.cx / 4; 

/* Determine ROP code to use */ 
if (poi->fsAttribute & MIA_DISABLED) 
ropCode = DBM_HALFTONE; 
else 

ropCode = DBM_NORMAL; 

/* Set the source rectangle and draw the bitmap. */ 

Recti.xLeft = yOffset; 

Recti.yBottom = 0L; 

Recti.xRight = yOffset + bmlnfoOwnerDraw.cx / 4; 

Recti.yTop = bmlnfoOwnerDraw.cy; 

WinDrawBitmap (poi->hps,(HBITMAP)poi->hItem,&Rectl, 
(PPOINTL)&poi->rclItem, 0L, 0L, ropCode); 

/* Turn off attributes by default */ 
poi->fsAttribute = 

(poi->fsAttributeOld &= ~(MIA_CHECKED \ MIA_HILITED | 

MIA_FRAMED)); 

return; 


Pop-Up Menu Window 

Pop-up menu windows are also a new feature of OS/2 2.1. Although it was possible to 
simulate pop-up windows prior to this version, the addition of the WinPopupMenu API 
makes things a lot easier on the application developer. Essentially, a pop-up menu is 
much like a pull-down menu except that it can appear anywhere on the screen. The ap¬ 
plication has control over where the pop-up appears, the inital state of the pop-up, how 
menu selection occurs, and whether keyboard and mouse input are allowed. Normally, a 
pop-up menu is shown in response to some user input. For example, when the user presses 
the right mouse button in the client area, a pop-up may appear allowing the user to select 
a particular attribute. 
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The WinPopupMenu API is used to display a pop-up menu. The menu can be a menu 
loaded from a resource file with a call to WinLoadMenu, a menu created dynamically by 
the application with a call to WinCreateMenu, or a particular submenu extracted from an 
existing menu. One of the first things done in WinPopupMenu is to set the menu window 
style to MS_ROOT j MS_POPUP ] WS_SAVEBITS and remove the MS_ACTIONBAR style. 
This allows you to use any existing menu because PM will set the menu style to fit the 
style of a pop-up window. The WinPopupMenu API is defined as follows: 

BOOL WinPopupMenu (HWND hwndParent, HWND hwndOwner, HWND hWndMenu, 

LONG x, LONG y, ULONG idltem, USHORT fsOptions) 

hwndParent - Parent window handle 

hwndOwner - Owner window handle 

hWndMenu - Popup window handle 

x - x-position of popup menu. This position is relative to the 

parent window and specifies the lower-left corner of the 

menu. 

y - y-position of popup menu. This position is relative to the 

parent window and specifies the lower-left corner of the 

menu. 

idltem - Identifier of menu item to select if PU_POSITIONONITEM or 
PUSELECTITEM are specified in fsOptions. 
fsOptions - Pop-up menu positioning and state options: 

PU_POSITIONONITEM - Position the popup so that the item 

specified by idltem is directly below the 
pointer. The item specified by idltem is 
selected. 

PU_HCONSTRAIN - Ensure that the menu does not extend beyond 

the left or right edge of the screen. 

Adjust the position of the menu as required. 

PU_VCONSTRAIN - Ensure that the menu does not extend beyond 

the top or bottom edge of the screen. Adjust 
the position of the menu as required. 

PU_N0NE - Menu is displayed and left up with no initial 

selection state. The menu item idltem is 
selected if PU_SELECTITEM or PU_POSITIONONITEM 
are specified. 

PU_M0USEBUTT0N1DOWN - Menu is displayed with mouse button 1 and 

depressed and dismissed when mouse button 1 
is released. 

No menu item is initially selected. 

PU_M0USEBUTT0N2D0WN - Menu is displayed with mouse button 2 and 

depressed and dismissed when mouse button 2 
is released. 

No menu item is initially selected. 

PUJVI0USEBUTT0N3D0WN - Menu is displayed with mouse button 3 and 

depressed and dismissed when mouse button 3 is 
released. No menu item is initially selected. 
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PU SELECTITEM 


PU_M0USEBUTT0N1 
PU_M0USEBUTT0N2 
PU_M0USEBUTT0N3 
PU KEYBOARD 


Select the idltem if PU_N0NE is specified. 

If this item is in a submenu, then all owner 
submenus in the menu hierarchy are displayed. 

Mouse button 1 can be used for menu selection 

Mouse button 2 can be used for menu selection 

Mouse button 3 can be used for menu selection 

Keyboard can be used for menu selection. 


If PU_POSITIONONITEM is specified, the x and y coordinates are screen coordinates 
and are not relative to the parent window. If PU_MOUSEBUTTON 1 DOWN, 
PU_M0USEBUTT0N2D0WN, or PU_M0USEBUTT0N3D0WN are specified, PU_SELECTITEM is 
ignored. If PU_N0NE is specified but neither PU_SELECTITEM or PU_POSITIONONITEM 
are, the first item in the menu is selected. 


As an example, if we have a pop-up menu that we want to display so that the menu 
remains up when the mouse is released, is constrained to the boundaries of the screen, 
has an item selected, and has all input devices available for selection, we would use the 
following flags: 

PU_N0NE | PU_HCONSTRAIN | PU_VCONSTRAIN | PU_SELECTITEM | 
PU_M0USEBUTT0N1 | PU_M0USEBUTT0N2 | PU_M0USEBUTT0N3 | PU_KEYBOARD 

If we want the menu to be dismissed when button 1 is released, assuming that but¬ 
ton 1 was used to summon the pop-up, we would use the following flags: 


PU_M0USEBUTT0N1DOWN j PU_HCONSTRAIN | PU_VCONSTRAIN | PU_M0USEBUTT0N1 

The call to WinPopupMenu returns immediately, and the menu is processed like any 
other menu window. The following code clip loads a pop-up menu and displays it as a 
pop-up menu when the WM_BUTT0N2D0WN message is received. The menu is constrained 
to the screen, and the keyboard and mouse button 2 are allowed for menu input. This 
menu will remain up after the mouse button is released, and the first menu item will be 
selected by default: 

switch (msg) 

{ 

case WM_BUTT0N2D0WN: 

if (!hWndPopupMenu) 

hWndPopupMenu = WinLoadMenu (HWND_OBJECT, 0, C0L0R_MENU); 
WinPopupMenu (hWnd, hWnd, hWndPopupMenu, 

SHORT1FROMMP(mpl), SH0RT2FR0MMP(mpl), 0, 

PUJHCONSTRAIN 1 PU_VCONSTRAIN \ PU_KEYBOARD | 
PU_M0USEBUTT0N2); 
break; 

} 


Note that the menu is only loaded once and not each time that the WinPopupMenu is 
called. The menu window handle is not destroyed when the menu is dismissed, so it is 
not necessary to load it everytime. Doing so would result in a new menu window being 
created each time and would eventually utilize all the window resources in the system. 
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However, you can use the WMJVIENUEND notification message to know when the menu 
has been hidden and it is okay to destroy the pop-up window. 

In our application, we will use a single pop-up menu to set both the window back¬ 
ground color and the text color. The window background color will be set by activating 
the pop-up menu with mouse button 1, and the text color will be set by activating the 
pop-up menu with mouse button 2. Each version of the pop-up will behave differently. 
The pop-up menu is defined in the resource file: 


/* menu, 

.h */ 



#define 

C0L0R_ 

MENU 

100 

#define 

IDC_C0L0R 

101 

#define 

IDBMP_ 

_0DITEM1 

56 

#define 

IDBMP~ 

0DITEM2 

57 

#define 

IDBMP] 

0DITEM3 

58 

/* menu. 

rc */ 




MENU COLORJVIENU 
{ 


} 


MENUITEM 

MENUITEM 

MENUITEM 

MENUITEM 


IDC_C0L0R, MIS_STATIC 
IDBMP_0DITEM1, MIS_OWNERDRAW 
IDBMPJDDITEM2, MIS_OWNERDRAW 
IDBMP_0DITEM3, MISJDWNERDRAW 


MIS_BREAK 
MIS_BREAK 
MIS BREAK 


The first menu item is a MIS_STATIC item with no text. The text for this item will be 
set to either "Window Color" or "Text Color" depending on the color that is being set. 
This field will act as a menu description field. The other three items are all MISJDWNERDRAW 
menu items that will use the code discussed in the previous section. All items in this 
pop-up are aligned horizontally. 

The specific color will be set when the menu items are selected. Two variables will 
contain the current settings for these colors. These color values are RGB (Red, Green, 
Blue) color values. If the Red button is selected, the color red will either be added or re¬ 
moved from the current color, likewise for Green and Blue: 

LONG lWindowColor = 0X00FFFFFF; 

LONG ITextColor = 0x00000000; 

/* RED GREEN BLUE */ 

LONG IColorTable[3] = { 0X00FF0000, 0X0000FF00, 0X000000FF }; 

switch (msg) 

{ 

case WM_COMMAND: 

case IDBMP_0DITEM1: 
case IDBMPJDDITEM2: 
case IDBMPJDDITEM3: 

{ 

USHORT usChecked; 
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/* Toggle the checkmark flag */ 
usChecked = 

LOUSHORT(WinlsMenuItemChecked (hColorMenu, L0USH0RT(mp1))); 
usChecked MIA_CHECKED; 

WinCheckMenuItem (hColorMenu, L0USH0RT(mp1), usChecked); 

/* Toggle the color field */ 
if (bWindowColor) 

lWindowColor * = lColorTable[L0USH0RT(mp1)-IDBMP_0DITEM1]; 
else 

ITextColor * = lColorTable[LOUSHORT(mp1)-IDBMP_0DITEM1]; 
WinlnvalidateRect (hWnd,NULL,FALSE); 
break; 


break; 


} 

The pop-up menu is initialized during the WM_INITMENU message. This processing 
checks the menu items when the color is included in the current color setting: 

case WM_INITMENU: 

else if (mp2 == hColorMenu) 

{ 

USHORT Pos; 

for (Pos = 0; Pos < 3; Pos++) 

WinSendMsg (hColorMenu, MM_SETITEMATTRBYPOS, 

MPFR0M2SH0RT(Pos+1,0), 

MPFR0M2SH0RT(MIA_CHECKED, 
bWindowColor ? 

((lWindowColor & lColorTable[Pos]) ? MIA_CHECKED : 0) : 
((ITextColor & lColorTable[Pos]) ? MIA_CHECKED : 0))); 

} 

break; 

Our pop-up menu is loaded once during the WM_CREATE message processing, and the 
menu item bitmaps used in the DrawOwnerltem are set for each item: 

/* Load the color pop-up menu */ 

hColorMenu = WinLoadMenu (HWND_OBJECT,0,C0L0R_MENU); 

/* Load and set the owner draw bitmap handles */ 
SetOwnerDrawBitmapHandles (hPS,hColorMenu); 

With the pop-up menu loaded, we are ready to display it when the mouse button 
messages are received. We are going to do something quite a bit different in displaying 
our menus. Normally, the pop-up menu is displayed with the lower-left corner positioned 
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at the pointer position. We want our pop-ups to display with either the upper-left or 
upper-right corner positioned at the pointer position. To do this, we will need to deter¬ 
mine the size of the pop-up menu. When a menu is about to be displayed, PM sends a 
WM_ADJUSTWINDOWPOS message to the menu, and the menu window calculates its size 
and returns it in the SWP structure passed with the WM_ADJ USTWI NDOWPOS message. This 
information can then be used to offset the current pointer position so that the pop-up 
menu displays with the upper corner aligned with the pointer. The function PlacePopup 
will handle this for us: 

VOID PlacePopup (HWND hWndOwner, HWND hWndMenu, 

ULONG x 3 ULONG y, BOOL bRight, ULONG ulFlags) 

/* We need to get the height of the menu because WinPopupMenu will 
position the menu with the lower-left corner of the menu at the 
coordinates passed. By sending a WM_ADJUSTWINDOWPOS message to 
the menu it will fill in the swp structure of the menu with its 
size. 

*/ 

SWP Swp; 

ULONG ulStyle; 

ulStyle = WinQueryWindowULong (hWndMenu,QWL_STYLE) & ~MS_ACTIONBAR; 

WinSetWindowULong (hWndMenu,QWL_STYLE,ulStyle); 

WinQueryWindowPos(hWndMenu, (PSWP)&Swp); 

Swp.f1 = SWP_M0VE | SWP_SIZE; 

Swp.hwndlnsertBehind = HWND_T0P; 

/* Set owner to frame here so that WM_MEASUREITEM messages are 
sent to the frame window for processing -- in case menu is 
ownerdraw */ 

WinSetOwner (hWndMenu,hWndOwner); 

WinSendMsg(hWndMenu, WM_ADJUSTWINDOWPOS, (MPARAM)(PSWP)&Swp, NULL); 

WinPopupMenu (hWndOwner,hWndOwner,hWndMenu, 
bRight ? x : x - Swp.cx, y - Swp.cy, 0, 

PU_HCONSTRAIN j PU_VCONSTRAIN j PU_KEYBOARD J 
PU_M0USEBUTT0N1 | ulFlags); 

return; 

} 


The hWndOwner parameter is both the owner and parent ofthe pop-up. The hWndOwner 
window will receive all notification messages from the pop-up. hWndMenu is the handle 
of the pop-up menu; x and y are the coordinates of the current pointer position. The 
parameter bRight specifies if the menu should display to the right ofthe pointer or to 
the left ofthe pointer. ulFlags are additional flags for the WinPopupMenu call. 
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Before sending the WM_ADJUSTWINDOWPOS message, we must make sure the style of 
the menu window does not include the MS_ACTIONBAR style. This will cause the size cal¬ 
culation to be performed for a submenu rather than an actionbar menu style: 

ulStyle = WinQueryWindowULong (hWndMenu,QWL_STYLE) & ~MS_ACTIONBAR; 
WinSetWindowULong (hWndMenu,QWL_STYLE,ulStyle); 

Next, we query the current position of the menu and set the f 1 field to SWP_MOVE ] 
SWP_SIZE. This tells PM that it needs to calculate a new size and position for the menu: 

WinQueryWindowPos(hWndMenu, (PSWP)&Swp); 

Swp.fl = SWPJ/IOVE | SWP_SIZE; 

Swp.hwndlnsertBehind = HWND_T0P; 

The next step is very important, especially in our case, because we are using ownerdraw 
menu items. The owner of the menu window will be automatically set when the 
WinPopupMenu is called; however, at this point it will be whatever the previous owner 
was. In our case, it will initially be HWND_OBJECT because the menu was loaded with 
HWND_OBJECT as its owner. We set the owner of the menu window because, in calculat¬ 
ing the size of the menu, PM will send a WM_MEASUREITEM message to the menu’s owner 
for each MIS_OWNERDRAW menu item. We must make sure that our ClientWndProc re¬ 
ceives those messages: 

WinSetOwner (hWndMenu,hWndOwner); 

WinSendMsg(hWndMenu, WM_ADJUSTWINDOWPOS, (MPARAM)(PSWP)&Swp, NULL); 

The WM_ADJUSTWINDOWPOS is sent to the window causing the calculation of the menu 
size. We then use the Swp. cx and Swp. cy fields to offset the position of the menu: 

WinPopupMenu (hWndOwner,hWndOwner,hWndMenu, 

bRight ? x : x - Swp.cx, y - Swp.cy, IDBMP_0DITEM1, 

PU_HCONSTRAIN | PU_VCONSTRAIN | PU_KEYBOARD | 

PUJ/10USEBUTT0N1 \ ulFlags); 

If bRight is TRUE, the menu will be positioned with the left corner of the menu at 
the pointer position. Otherwise, it will be positioned with the right corner of the menu 
at the pointer position. 

In activating the pop-up menu, the pop-up used in setting the window color will be 
summoned by mouse button 1, and it will remain up after the mouse button is released. 
The text color pop-up menu will be summoned by mouse button 2, and it will be dis¬ 
missed when mouse button 2 is released: 

case WM_BUTT0N1DOWN: 
bWindowColor = TRUE; 

WinLoadString (hab, 0, IDS_WIND0WC0L0R, sizeof(szColon), 
szColor); 

WinSendMsg (hColorMenu,MM_SETITEMTEXTBYPOS, 

MPFROMSHORT (0) ,MAKE_16BIT_P0INTER(szColor)); 
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/* Call WinDefWindowProc so that window is activated */ 
mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 

PlacePopup (hWnd, hColorMenu, 

SH0RT1FR0MMP(mp1),SH0RT2FR0MMP(mpl),FALSE, 

PU_N0NE); /* Allow button to be released */ 
break; 

case WM_BUTT0N2D0WN: 
bWindowColor = FALSE; 

WinLoadString (hab, 0, IDS_TEXTCOLOR, sizeof(szColor), szColor); 
WinSendMsg (hColorMenu,MM_SETITEMTEXTBYPOS, 

MPFROMSHORT(0),MAKE_16BIT_P0INTER(szColor)); 

/* Call WinDefWindowProc so that window is activated */ 
mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 

PlacePopup (hWnd, hColorMenu, 

SHORT1FROMMP(mpl),SH0RT2FR0MMP(mpl),TRUE, 
PUJVI0USEBUTT0N2D0WN) ; 
break; 

There are three steps in handling each mouse message. The first step is to set the text 
of the first menu item to indicate the color that is being set. These strings are loaded from 
the resource file and the text set using the MM_SETITEMTEXTBYPOS message. We set the 
global variable bWindowColor to indicate if we are setting the window color or text color. 
The next step is also important. PM uses the WM_BUTTONxDOWN messages to activate the 
window. When WinDefWindowProc receives the WM_BUTTONxDOWN message, it calls 
WinSetActiveWindow to activate the window that is beneath the pointer. If we do not 
pass the button down message to WinDefWindowProc, the window will not become 
active if it is not currently active. To see what would happen, remove the call to 
WinDefWindowProc, start the application, and then click another application so that the 
menu application is deactivated. Then click mouse button 1 in the client area of the menu 
application. The pop-up menu will appear, but the application will not become active. 

Finally, we make the call to PlacePopup with the client window as the owner and 
passing the current pointer position as the x and y position. For WM_BUTT0N1 DOWN, we 
use the PU_N0NE flag so that the menu remains up after the mouse button is released. 
For WM_BUTT0N2D0WN, we use the PU_M0USEBUTT0N2D0WN flag so that the menu is dis¬ 
missed when the mouse button is released. Notice the differences in the initial selection 
state of the pop-up when activated with the two mouse buttons. 


Replacing the Actionbar Menu 

In many Multiple Document Interface (MDI) applications, it is necessary to update the 
actionbar menu to reflect the selections for the currently selected child window. For 
example, one child window may require the following actionbar menu: 

File Edit View Style Window 
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and a second child window may require the following actionbar menu: 

Image Options Color Window 

There are two ways to handle the change in menu when a child window is activated. 
The first is to individually remove each menu item and insert the new items. This is time- 
consuming and rather undesirable. The second is to load two different menus and switch 
between the two. Remember that the actionbar window has an identifer of FID_MENU 
and that this menu is recognized by the frame window as a frame control window. All 
that is required is to replace the current FID_MENU window with the new FID_MENU and 
tell the frame window to redraw the menu frame control. To swap the menus, we could 
use the following SwapActionBarMenu function: 

VOID SwapActionBarMenu (HWND hWndFrame, HWND hWndNewMenu) 

{ 

ULONG ulStyle; 

HWND hWndCurrentMenu = WinWindowFromID (hWndFrame, FID_MENU); 

/* If there is a current menu, change its parent and owner */ 
if (hWndCurrentMenu) 

{ 

WinSetParent (hWndCurrentMenu, 

WinQueryObjectWindow (HWND_DESKTOP),FALSE); 

WinSetOwner (hWndCurrentMenu, 

WinQueryObjectWindow (HWND_DESKTOP)); 

} 

/* Make sure menu styles are properly set and identifer 
is FID_MENU */ 

ulStyle = WinQueryWindowULong (hWndNewMenu, QWL_STYLE); 

UlStyle != MS_ROOT | MS_ACTIONBAR [ WS_CLIPSIBLINGS; 
ulStyle &= ~WS_SAVEBITS; 

WinSetWindowULong (hWndNewMenu, QWL_STYLE, ulStyle); 
WinSetWindowUShort (hWndNewMenu, QWS_ID, FID_MENU); 

/* Change parent and owner to frame window */ 

WinSetParent (hWndNewMenu, hWndFrame, FALSE); 

WinSetOwner (hWndNewMenu, hWndFrame); 

/* Notify frame window of new frame control window */ 

WinSendMsg (hWndFrame, WM_UP DATE FRAME, FCFJVIENU, NULL); 
return; 

} 

We first check if there is an existing menu and effectively remove the menu from the 
frame by setting its parent and owner to the object window. The new menu must have 
the proper styles or else it will not format correctly; the identifier of the new menu win¬ 
dow must be FIDJVIENU, or the frame window will not find it. The parent and owner of 
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the new menu are set to the frame window. The WMJJP DATE FRAME is sent to the frame 
to notify it that a new menu control has been added, and it needs to reformat and redraw 
itself. 

Assume that we have loaded two menus: 

hWndMenul = WinLoadMenu (HWND_OBJECT, 0, MAIN_MENU1); 
hWndMenu2 = WinLoadMenu (HWND_OBJECT, 0, MAIN_MENU2); 

When child window 1 becomes active, we would call the following: 

SwapActionBarMenu (hWndMDIFrame, hWndMenul); 

and when child window 2 becomes active, we would call this: 

SwapActionBarMenu (hWndMDIFrame, hWndMenu2); 

Using the Same Submenu in Multiple Menus 

In an MDI application, there is usually one menu option that lists the current child win¬ 
dow applications. This is usually the “Window” menu option, and as child windows are 
created and destroyed, menu items are added and removed from this pull-down menu. A 
“Window” menu item is defined for each actionbar menu, and each pull-down must be 
updated whenever a new item is added or removed. PM does not provide a way to specify 
the same submenu in multiple menus. In fact, if you call MM_INSERTITEM and use the 
same submenu window handle in more than one menu item, the submenu will display 
properly only for the last menu item that was added. Any other menu items attempting 
to display the submenu will have the submenu display, and the entire chain of menus 
above it will be dismissed. This is because the owner of the submenu is set when the item 
is inserted, and the owner of the menu incorrect when it is displayed. 

It would nice if we could somehow use the same submenu in multiple menu items 
and have the owner updated as required. This would be especially helpfiil for MDI ap¬ 
plication menus so that we could define the “Window” submenu once, update it as child 
windows are created and destroyed, and have it displayed properly for each actionbar menu. 
This can be accomplished by using the undocumented messages MM_PORTHOLEINIT and 
MM_QUERYITEMBYPOS. The MM_PORTHOLEINIT message is sent up the owner chain just 
prior to summoning the pop-up menu and gives us enough information to allow us to 
set the owner: 

MM_PORTHOLEINIT 0x01fb 

SHORT1FROMMP (mpl) = position of submenu in the menu 

SH0RT2FR0MMP (mpl) = attribute of the menu item 

mp2 = menu handle containing the item 

When the frame window receives this message, it can query the menu handle for the 
menu item at the specified position and set the owner of the submenu to the menu handle. 
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switch (msg) 

{ 

case MM_PORTHOLEINIT: 

{ 

MENUITEM mi; 

WinSendMsg ((HWND)mp2, MM_QUERYITEMBYPOS, SH0RT1FROMMP(mpl), 
MAKE_16BIT_P0INTER(&mi)); 

if (WinQueryOwner (mi.hwndSubMenu,QW_0WNER) != (HWND)mp2) 

{ 

WinSetOwner (mi.hwndSubMenu, (HWND)mp2); 

WinSetWindowUShort (mi.hwndSubMenu, QWS_ID, mi.id); 

} 

break; 

} 

} 

The MM_QUERYITEMBYPOS message retrieves the MENUITEM structure for the menu item 
at the specified position. If the owner of the submenu about to be displayed is not equal 
to the menu that is summoning it, we set the owner of the submenu to the summoning 
menu. We also set the identifier of the submenu to the identifier of the MENUITEM 
because this submenu may be referenced by many different identifiers. 

You still need to set the submenu handle for each menu item that wants to share 
the particular submenu. This can be done when the item is added to the menu 
(MM_INSERTITEM) or changed later (MM_SETITEM). 

Changing the System Menu 

Finally, let’s add an About option to the system menu. The system menu is just another 
menu window with an ID of FID_SYSMENU (see Figure 5.12). It contains one menu item, 
which is a bitmap menu item with a submenu. To add an item to the submenu, we must 
get the handle to the submenu. We do this by querying the first item in the system menu. 
Once we have that, we can append a separator and an "About. . ." menu item. Selecting 
this option in the application will display an informational dialog box (see Figure 5.13). 

VOID AddAboutToSystemMenu(HWND hWndFrame) 

{ 

MENUITEM mi; 

HWND hWndSysSubMenu; 

WinSendMsg (WinWindowFromID (hWndFrame, FID_SYSMENU), 
MM_QUERYITEMBYPOS, 0L, MAKE_16BIT_P0INTER(&mi)); 
hWndSysSubMenu = mi.hwndSubMenu; 
mi.iPosition = MIT_END; 

mi.afStyle = MIS_SEPARATOR; 

mi.afAttribute = 0; 

mi.id = -1; 
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mi.hwndSubMenu = 0; 

mi.hltem = 0; 

WinSendMsg (hWndSysSubMenu, MM__INSERTITEM, MPFROMP (&mi), NULL); 
mi.afStyle = MIS_TEXT; 

mi.id = IDM_ABOUT; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), 

"About 
return; 


Figure 5.12. 
System menu with 
added menu item. 
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Menu Messages 

Many of the common menu messages and some undocumented messages are discussed 
in the following section. 

Menu Messages 

The following is a list of the menu messages. This list is followed by a description of the 
more frequently used menu messages. 


Message 

MMJNSERTITEM 

MM_DELETEITEM 

MM_QUERYITEM 

MMLSETITEM 

MM_QUERYITEMCOUNT 

MM_STARTMENUMODE 

MM_ENDMENUMODE 

MM_REMOVEITEM 

MM_SELECTITEM 

MM_QUERYSELITEMID 

MMLQUERYITEMTEXT 

mm_queryitemtextlen gth 

MM_SETITEMHANDLE 

MM_SETITEMTEXT 

MMJTEMPOSmONFROMID 

MMJTEMIDFROMPOSITION 

MM_QUERYITEMATTR 


Value 

Description 

0x0180 

Insert a menu item into a 

menu. 

0x0181 

Delete a menu item from 

a menu. 

0x0182 

Query MENUITEM 
structure of an item. 

0x0183 

Set the MENUITEM 
structure of an item. 

0x0184 

Query number of items 
in menu. 

0x0185 

Start menu selection of a 

menu. 

0x0186 

End all menu selections. 

0x0188 

Remove a menu item 
from a menu. 

0x0189 

Set selection state of an 
item. 

0x018a 

Query the currently 
selected item ID. 

0x018b 

Query the text of an item. 

0x018c 

Query the text length of 
an item. 

0x018d 

Set the bitmap or 
ownerdraw handle. 

0x018e 

Set the text of an item. 

0x018f 

Query index of an item 
identifier. 

0x0190 

Query the identifier of an 
item. 

0x0191 

Query the attributes of an 
item. 
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Message 

MM_SETITEMATTR 

MMJSITEMVALID 

MM_QUERYITEMRECT 

MM_SUMMON 

MM_DISMISS 

MM_STARTTRACKING 

MM_SUMMONCHAIN 

MM_DISMISSCHAIN 

MM_ISCHAINENABLED 

MM_QUERYMENUSAVEDFOCUS 

MM_SETMENUSAVEDFOCUS 

MM_SELECTITEMBYPOS 

MM_MATCHMNEMONIC 

MM_DELETEITEMBYPOS 

MM_REMOVEITEMBYPOS 

MM_QUERYITEMBYPOS 

MM_SETITEMBYPOS 

MM_QUERYITEMATTRBYPOS 

MM_SETITEMATTRBYPOS 


Value 

Description 

0x0192 

Set the attributes of an 
item. 

0x0193 

Query if item is select¬ 
able. 

0x0194 

Query bounding rect¬ 
angle of an item. 

0x0196 

Cause menu to be 
displayed. 

0x0197 

Cause menu to be 
hidden. 

0x0198 

Capture mouse and begin 
tracking. 

0x0199 

Display menu and all 
owner menus. 

0x019a 

Hide menu and all owner 

menus. 

0x019b 

Are menu and all owners 
enabled. 

0x019c 

Query window to receive 
focus at end. 

0x019d 

Set window to receive 
focus at end. 

0x019e 

Set selection state by its 
position. 

0x0 lfO 

Find match of mnemonic 
char in menu. 

0x0 lfl 

Delete a menu item by its 
position. 

0x01 f2 

Remove a menu item by 
its position. 

0x016 

Query MENUITEM by 
its position. 

0x0 lf4 

Set MENUITEM by its 
position. 

0x016 

Query the attribute by its 
position. 

0x0 lf6 

Set the attribute by its 
position. 
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Message 

Value 

Description 

MM_QUERYITEMTEXTBYPOS 

0x0 lf7 

Query text of 
item by its 
position. 

mm_queryitemtextlen gthbypos 

0x0 lf8 

Query text length 
by its position. 

MM_SETITEMTEXTBYPOS 

0x0 lf9 

Set text of item by 
its position. 

MM_SETITEMHANDLEBYPOS 

0x01 fa 

Set bitmap or 
ownerdraw 
handle by its 
position. 

MM_SETITEMCHECKMARKBYPOS 

0x0 lfc 

Set checkmark 
bitmap by its 
position. 

MM_SETITEMCHECKMARK 

0x0210 

Set checkmark to 
display for item. 


MMJNSERTITEM— 0x0180 

This message is sent to insert a menu item into a menu: 

mpl = pmenuitem (PMENUITEM) Points to a MENUITEM structure for 

the item to insert. 

mp2 = pltemText (PSTRL) Text of menu item. 


The return value specifies the index of the inserted item. 

This example inserts the menu item Open File as the first item in the menu: 


MENUITEM mi; 
mi.iPosition 
mi.afStyle 
mi.afAttribute 
mi. id 

mi.hwndSubMenu 
mi.hltem 


0 ; 

MIS_TEXT; 
0 ; 

0x100; 

NULL; 

NULL; 


WinSendMsg (hWndMenu, MM_INSERTITEM, &mi, "-Open File..."); 

The special identifier MIT_END can be used for the iPosition field to insert the item 
at the end of the list of items for the menu. 
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MM_DELETEITEM—0x0181 

This message is sent to delete a menu item from a menu. It also destroys any submenu 
windows and deletes the bitmap associated with the menu item if the bitmap was not 
created by the application. 

mpl = SH0RT1FROMMP (mp 1) Identifier of item to query. 

SH0RT2FR0MMP (mpl) TRUE Include submenus in the 

search. 

FALSE Do not include submenus in 
the search. 

mp2 is not used. 

The return value specifies the number of items remaining in the menu. 

This example deletes the menu item with identifer 0x101 from the menu and searches 
the submenus if it is not found in the menu: 

WinSendMsg (hWndMenu, MMJDELETEITEM, MPFROM2SHORT(0x0101, TRUE), NULL) 

MM_DELETEITEMBYPOS—0x01 ft 
(UNDOCUMENTED MESSAGE) 

This message is sent to delete a menu item by position from a menu. This message will 
only delete an item in the menu specified. It also destroys any submenu windows and 
deletes the bitmap associated with the menu item if the bitmap was not created by the 
application. 

mpl = Position of item to delete. 
mp2 is not used. 

The return value specifies the number of items remaining in the menu. 

This example deletes the menu item in position 3 from the menu: 

WinSendMsg (hWndMenu, MM_DELETEITEMBYPOS, 3, 0L); 

MM_QUERYITEM—0x0182 

This message is sent to retrieve the definition of a menu item. This message will not 
retrieve the text for MIS_TEXT items; use the MM_QUERYITEMTEXT message to retrieve the 
text. 


mpl = SH0RT1FROMMP(mpl) 
SH0RT2FR0MMP(mpl) 


TRUE 


Identifier of item to delete. 
Include submenus in the 
search. 
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FALSE Do not include 

submenus in the search. 

mp2 = pmenuitem (PMENUITEM) Points to a MENUITEM 

structure to be filled in. 


The return value is TRUE if the request is successful. 

This example queries the definition for the menu item with identifer 0x101 from the 
menu and searches the submenus if it is not found: 

MENUITEM mi; 

WinSendMsg (hWndMenu, MM_QUERYITEM, MPFROM2SHORT(0x0101, TRUE), &mi); 

MM_QUERYITEMBYPOS—0x01 f 3 
(UNDOCUMENTED MESSAGE) 

This message is sent to retrieve the definition of a menu item by its position. This mes¬ 
sage will only query an item in the specified menu. This message will not retrieve the text 
for MIS_TEXT items; use the MM_QUERYITEMTEXTBYPOS message to retrieve the text. 

mpl = Position of item in menu (Use MPFROM2SHORT(position,0)). 

mp2 = pmenuitem (PMENUITEM) (16-bit pointer) 

Points to a MENUITEM structure to be 
filled in. 

The return value is TRUE if the request is successful. 

This example queries the definition for the menu item at position 3: 

MENUITEM mi; 

WinSendMsg (hWndMenu, MM_QUERYITEMBYPOS, 3, MAKE_16BIT_P0INTER(&mi)); 


MM_SETITEM— 0x0183 

This message is sent to set the definition of a menu item. The iPosition field of the 
MENUITEM structure is ignored because you cannot change the position of a menu item. 
If the submenu or bitmap handle is changing, the previous submenu window handle or 
bitmap handle is not deleted during the handling of this message. 


Tmpl = SH0RT1FR0MMP(mp1) 

SH0RT2FR0MMP(mpl) TRUE 

FALSE 


mp2 =pmenuitem (PMENUITEM) 


Is reserved and set to zero. 
Include submenus in he 
search. 

Do not include submenus in 
the search. 

Points to a MENUITEM 
structure for the item to set. 


The return value is TRUE if the request is successful. 
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This example queries the current item definition for the menu with identifier 0x101 
and changes the menu identifier to 0x202: 

MENUITEM mi; 

WinSendMsg (hWndMenu, MM_QUERYITEM, MPFROM2SHORT(0x0101, TRUE), &mi); 
mi.id = 0x202; 

WinSendMsg (hWndMenu, MM_SETITEM, MPFR0M2SH0RT(0,TRUE), &mi); 

MM_SETITEMBYPOS—0x01 f4 
(UNDOCUMENTED MESSAGE) 

This message is sent to set the definition of a menu item by its position. This message 
will only set an item in the specified menu. The iPosition field of the MENUITEM struc¬ 
ture is ignored because you cannot change the position of a menu item. If the submenu 
or bitmap handle is changing, the previous submenu window handle or bitmap handle 
is not deleted during the handling of this message. 

mpl = Position of item in menu. 

mp2 = pmenuitem (PMENUITEM) (16-bit pointer) 

Points to a MENUITEM structure to be set. 

The return value is TRUE if the request is successful. 

This example queries the current item definition for the item at position 3 and flips 
the MIA_CHECKED attribute: 

MENUITEM mi; 

WinSendMsg (hWndMenu, MM_QUERYITEMBYPOS, 3, MAKE_16BIT_P0INTER(&mi)); 
mi.atAttribute A = MIA_CHECKED; 

WinSendMsg (hWndMenu, MM_SETITEMBYPOS, 3, MAKE_16BIT_P0INTER(&mi)); 

MM_QUERYITEMCOUNT— 0x0184 

This message is sent to query the number of items in the menu. 

mpl is not used. 
mp2 is not used. 

The return value is the number of items in the menu. 

This example queries the number of items in the menu: 

USHORT usCount = WinSendMsg (hWndMenu, MM_QUERYITEMCOUNT, 0, 0); 

MM_STARTMENUMODE—0x0185 

This message is sent to either the system menu (FID_SYSMENU) or actionbar menu 
(FID_MENU) when either the SC_SYSMENU or SC_APPMENU menu is summoned from the 
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WM_SYSCOMMAND message. This message is ignored for pop-up menu windows. This mes¬ 
sage is generated when the system menu or application menu is activated by pressing and 
releasing the ALT key in an application window. It causes the submenu of the system 
menu or the actionbar menu to become active. 


mpl = SH0RT1FROMMP (mpl) 

TRUE 

Show the submenu of the first 
item. 


FALSE 

Do not show the submenu of 
the first item. 

SH0RT2FR0MMP (mpl) 

TRUE 

Resume the user interaction of 
the currently active menu. 


FALSE 

Resume the user interaction 
from the actionbar. 


mp2 is not used. 


The return value is TRUE if the request is successful. 

When the window has a system menu and the ALT key is pressed and released, the 
following message is sent to the system menu window: 

WinSendMSg (hWndSysMenu, MM_STARTMENUMODE, MPFR0M2SH0RT(TRUE, FALSE), 

0 ); 

If the ALT key is pressed and the window does not have a system menu but it does 
have an actionbar menu, the following message is sent to actionbar menu window: 

WinSendMsg (hWndMenu, MM_STARTMENUMODE, MPFROM2SHORT(FALSE, FALSE), 

0 ); 

This example will cause the actionbar menu to become active and the first menu item 
to be selected (if the first item has a submenu, the submenu will be displayed): 

WinSendMsg (hWndMenu, MM_STARTMENUMODE, MPFR0M2SH0RT(TRUE, FALSE), 

0 ); 


MM_ENDMENUMODE—0x0186 

This message is sent to a menu window to terminate the menu selection. When the menu 
window receives this message, it sends the undocumented message MM_DISMISSCHAIN 
(0x019a) to the menu window, which causes the menu and all displayed submenus to be 
dismissed. 

mpl = SH0RT1FROMMP(mpl) TRUE Dismiss the submenu window. 

FALSE Do not dismiss the submenu 

window. 

mp2 is not used. 

The return value is zero. 


236 



Chapter 3 Menus 


This example uses the MM_ENDMENUMODE message to close the current menu 
processing: 

WinSendMsg (hWndMenu, MM_ENDMENUMODE, MPFROMSHORT(TRUE), 0); 

MM_REMOVEITEM— 0x0188 

This message is sent to remove a menu item from a menu. In contrast to the 
MM_DELETEITEM message, this message does not destroy any submenus or delete any 
bitmaps associated with the menu item. 

mpl = SH0RT1FROMMP (mpl) Identifier of item to remove. 

SH0RT2FR0MMP (mpl) TRUE Include submenus in the 

search. 

FALSE Do not include submenus in 

the search. 

mp2 is not used. 

The return value specifies the number of items remaining in the menu. 

This example removes the menu item with identifer 0x101 from the menu and searches 
the submenus if it is not found in the menu: 

WinSendMsg (hWndMenu, MM_REM0VEITEM, MPFROM2SHORT(0x0101, TRUE), NULL) 

MM_REMOVEITEMBYPOS—0x01 £2 
(UNDOCUMENTED MESSAGE) 

This message is sent to remove a menu item by position from a menu. This message will 
only remove an item in the menu specified. In contrast to the MM_DELETEITEMBYPOS 
message, this message does not destroy any submenus or delete any bitmaps associated 
with the menu item. 

mpl = Position of item to remove. 
mp2 is not used. 

The return value specifies the number of items remaining in the menu. 

This example removes the menu item in position 3 from the menu: 

WinSendMsg (hWndMenu, MM_REM0VEITEMBYP0S, 3, 0L); 

MM_SELECTITEM— 0x0189 

This message is sent to set the selection state of a menu item. If the item being selected is 
in a submenu that is not currently displayed, then the menu is summoned and displayed. 
If the item selected is in a submenu, the item is selected and the selection state of the 
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menu owning the submenu is also set. This process continues up the menu hierarchy 


e top-level menu is reached. 

mpl - SHORT1FROMMP(mpl) 

MIT_NON 

Deselect all items in the 

other 


menu. 

Identifier of item to 

SH0RT2FR0MMP(mpl) 

TRUE 

select. 

Include submenus in the 


FALSE 

search. 

Do not include submenus 

mp2 - SH0RT1FROMMP(mp2) 


in the search. 

Reserved and set to zero. 

SH0RT2FR0MMP(mp2) 

TRUE 

Dismiss the menu and post 


FALSE 

WM_COMMAND, 
WM_SYSCOMMAND, or 
WM_HELP message. 

Do not dismiss the menu. 


The return value is TRUE if the selection was made or MIT_N0NE was specified. The 
return value is FALSE if the item is not selectable, the item was deselected, or MIT_NONE 
was not specified. 

This example uses the MM_SELEOTITEM message to select the menu item with identi¬ 
fier 0x302 and searches the submenus for the item, but does not dismiss the menu chain: 

WinSendMsg (hWndMenu, MM_SELECTITEM, MPFR0M2SH0RT(0x302,TRUE), 
MPFR0M2SH0RT(0,FALSE)); 


MM_SELECTITEMBYPOS—0x019e 
(UNDOCUMENTED MESSAGE) 

This message is sent to set the selection state of a menu item by its position. This message 
will set the selection state in the specified menu. If the item being selected is in a submenu 
that is not currently displayed, then the menu is summoned and displayed. If the item 
selected is in a submenu, the item is selected and the selection state of the menu owning 
the submenu is also set. This process continues up the menu hierarchy until the top- 
level menu is reached. 


mpl - MIT_FIRST 
MIT_LAST 
MITJMONE 

other 


First item in the menu. 

Last item in the menu. 
Deselect all items in the 
menu. 

Position of item in the menu. 


mp2 - SHORT1FROMMP(mp2) 


Reserved and set to zero. 
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SH0RT2FR0MMP (mp2) TRUE Dismiss the menu and post 

WM_COMMAND, 
WM_SYSCOMMAND, or 
WM_HELP message. 

FALSE Do not dismiss the menu. 

The return value is TRUE if the selection was made or MIT_N0NE was specified. The 
return value is FALSE if the item is not selectable, the item was deselected, or MIT_N0NE 
was not specified. 

This example uses the MM_SELECTITEMBYPOS message to select the first menu item 
in the menu and to dismiss the menu chain: 

WinSendMsg (hWndMenu, MM_SELECTITEMBYPOS, MIT_FIRST, 

MPFR0M2SH0RT(0,TRUE)); 


MMLQUERYSELITEMID— 0 x 018 a 

This message is sent to retrieve the identifier of the selected menu item. 


mpl = SHORT1FROMMP(mpl) 
SH0RT2FR0MMP(mp1) 


mp2 is not used. 


Reserved and set to zero. 
TRUE Find the selected item in the 

last submenu summoned. 
FALSE Find the selected item in the 

menu specified. 


The return value is MIT_N0NE if no menu item is specified or the identifier of the 
currently selected menu item. 

This example retrieves the identifier of the selected item in the menu recursing the 
submenus to find the last submenu summoned: 


SHORT sID = WinSendMsg (hWndMenu, MM_QUERYSELITEMID, 
MPFR0M2SH0RT(0,TRUE), 0); 


MM_QUERYITEMTEXT— 0x018b 

This message is sent to retrieve the text for a specified menu item. This message only 
applies to menu items with the MIS_TEXT style. The length of the text to be copied can 
be queried with the MM_QUERYITEMTEXTLENGTH message. Only the specified menu is 
searched for the item and no submenus are searched. 

Identifier of item to query the 
text. 


mpl = SH0RT1FROMMP(mpl) 
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SH0RT2FR0MMP (mp2) Maximum number of bytes to copy 

(includes the null termination 
character). 

mp2 = pltemtext (PSTRL) Pointer to buffer to copy text. 

The return value is the length of the string copied to pltemText. 

This example queries the text for the menu item with identifier 0x201: 

CHAR szBuffer[80]; 

WinSendMsg (hWndMenu, MM_QUERYITEMTEXT, 

MPFR0M2SH0RT(0x201,sizeof(szBuffer)), szBuffer); 

MM_QUERYITEMTEXTBYPOS—0x010 
(UNDOCUMENTED MESSAGE) 

This message is sent to retrieve the text for a menu item specified by its position in the 
menu. This message will only query an item in the menu specified. This message only 
applies to menu items with the MIS_TEXT style. The length of the text to be copied can 
be queried with the MM_QUERYITEMTEXTLENGTHBYPOS message. 

mpl = SHORT 1 FROMMP (mpl ) Position of the item to query the text. 

SH0RT2FR0MMP(mp2) Maximum number of bytes to copy 

(includes the null termination 
character). 

mp2 = pltemtext (PSTRL) Pointer to buffer to copy text 

(16-bit pointer). 

The return value is the length of the string copied to pltemText. 

This example queries the text for the menu item at position 4: 

CHAR szBuffer[80]; 

WinSendMsg (hWndMenu, MM_QUERYITEMTEXTBYPOS, 

MPFR0M2SH0RT(4,sizeof(szBuffer)), MAKE_16BIT_P0INTER(szBuffer)); 

MM_QUERYI TEMTEXTLEN GTH— 0x018c 

This message is sent to retrieve the text length for a specified menu item. This message 
only applies to menu items with the MIS_TEXT style. Only the specified menu is searched 
for the item and no submenus are searched. 

mpl = Identifier of item to query. 
mp2 is not used. 

The return value is the length of the string. 

This example queries the length of the text for the menu item with identifier 0x201: 
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SHORT sLen = WinSendMsg (hWndMenu, MM_QUERYITEMTEXTLENGTH, 

MPFROMSHORT(0x201), 0); 

MM_QUERYITEMTEXTLEN GTHBYPOS—0x01 f 8 
(UNDOCUMENTED MESSAGE) 

This message is sent to retrieve the text length for a menu item specified by its position in 
the menu. This message will only query an item in the menu specified. This message only 
applies to menu items with the MIS_TEXT style. 

mpl = Position of the item to query. 
mp2 is not used. 

The return value is the length of the string. 

This example queries the length of the text for the menu item at position 4: 

SHORT sLen = WinSendMsg (hWndMenu, MM_QUERYITEMTEXTLENGTHBYPOS, 
MPFROMSHORT(4), 0); 

MM_SETITEMHANDLE—0x018d 

This message is sent to change either the bitmap handle or owner draw handle for a speci¬ 
fied menu item. This message only applies to menu items with the MIS_BITMAP or 
MIS_0WNERDRAW style. 

mpl = SH0RT1 FROMMP (mpl) Identifier of item to query. 

mp2 = Item handle. 

The return value is TRUE if the request is successful. 

This example changes the bitmap handle of an MIS_BITMAP menu item with identi¬ 
fier 0x201; 

HBITMAP hNewBitmap = GpiLoadBitmap (hPS, 0, IDB_NEWBITMAP, 0, 0); 
WinSendMsg (hWnd, MM_SETITEMHANDLE, MPFROMSHORT(0x201), hNewBitmap); 

MM_SETITEMHANDLEBYPOS—0x01 fa 
(UNDOCUMENTED MESSAGE) 

This message is sent to change either the bitmap handle or owner draw handle for a menu 
item specified by its position in the menu. This message only applies to menu items with 
the MIS_BITMAP or MIS_0WNERDRAW style. This message will only set an item in the menu 
specified. 

mpl = Position of the item to query. 
mp2 = Item handle. 
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The return value is TRUE if the request is successful. 

This example changes the bitmap handle of an MISJ3ITMAP menu item at posh 
tion 4: 

HBITMAP hNewBitmap = GpiLoadBitmap (hPS, 0, IDB_NEWBITMAP, 0, 0); 
WinSendMsg (hWnd, MM_SETITEMHANDLEBYPOS, MPFROMSHORT(4), hNewBitmap); 

MM_SETITEMTEXT — 0x018e 

This message is sent to change the text of a menu item for a specified menu item. This 
message only applies to menu items with the MIS_TEXT style. 

mpl = SH0RT1FR0MMP(mp1) Identifier of item to query. 

mp2 = (PSTRL) Points to string. 

The return value is TRUE if the request is successful. 

This example changes the text of a MISJTEXT menu item with identifier 0x201: 
WinSendMsg (hWnd, MM_SETITEMTEXT, MPFROMSHORT(0x201) , "-Open File' 1 ); 

MM_SETITEMTEXTBYPOS—0x01 f 9 
(UNDOCUMENTED MESSAGE) 

This message is sent to change the text for a menu item specified by its position in the 
menu. This message only applies to menu items with the MIS_TEXT style. This message 
will only set an item in the menu specified. 

mpl - SHORT 1 FROMMP (mpl) Position of item to query. 

mp2 = (PSTRL) Points to string (16-bit pointer). 

The return value is TRUE if the request is successful. 

This example changes the text of a MIS_TEXT menu item at position 4: 

CHAR szBuffer[11] = "-Open File"; 

WinSendMsg (hWnd, MM_SETITEMTEXTBYPOS, MPFROMSHORT(4), 

MAKE_16BIT_P0INTER(szBuffer)); 

MM_ITEMPOSITIONFROMID— 0x018f 

This message is sent to retrieve the position of a menu item based on its identifier. The 
position returned is the menu item’s position in the menu or submenu in which it was 
found. 

mpl = SH0RT1 FROMMP (mpl ) Identifier of item. 

SH0RT2FROMMP (mpl) TRUE Include submenus in the 

search to find the item. 
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mp2 is not used. 


FALSE Do not search submenus to 

find the item. 


The return value is the zero-based index of the menu item if it is found or MIT_NONE 
if it is not found. 


This example searches for the index of a menu item with identifier 0x201 and does 
not search submenus for the item: 

SHORT slndex = WinSendMsg (hWndMenu, MM_ITEMPOSITIONFROMID, 
MPFR0M2SH0RT (0x201, FALSE), 0); 


MM_ITEMIDFROMPOSITION—0x0190 

This message is sent to retrieve the identifier of a menu item based on its position in the 
menu. This message will only search the menu that is specified. 

mpl = SH0RT1FROMMP (mpl) Position of item to find. 

SH0RT2FR0MMP (mpl) Reserved and set to zero. 

mp2 is not used. 

The return value is the identifier of specified item or MIT_N0NE if it was not found. 

This example searches for the identifier of the menu item at position 2: 

SHORT sID = WinSendMsg (hWndMenu, MM_ITEMIDFR0MP0SITI0N, 

MPFR0M2SH0RT (2, 0), 0); 


MM_QUERYITEMATTR—0x0191 

This message is sent to retrieve the current attributes of a menu item. The attributes 
returned are the current state values of the menu item ANDed with the attribute mask 
specified in mp2. It does not change any of the attributes of the menu item. 


mpl = SH0RT1FROMMP (mpl) 


Identifier of item to query. 

SH0RT2FR0MMP (mpl) 

TRUE 

Include submenus in the 
search to find the item. 


FALSE 

Do not search submenus to 
find the item. 


mp2 = Requested attributes mask. 

The return value is the current state of the attributes requested. 

This example queries the attributes of the menu item with identifier 0x201 and does 
not search submenus. We are only interested in the MIA_CHECKED and MIA_DISABLED 
attributes: 
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USHORT usAttrs = WinSendMsg (hWndMenu, MM_QUERYITEMATTR, 

MPFR0M2SH0RT (0x201, FALSE), MIA_CHECKED | MIA_DISABLED); 

MM_QUERYITEMATTRBYPOS—0x0 If 5 
(UNDOCUMENTED MESSAGE) 

This message is sent to retrieve the current attributes of a menu item specified by its 
position in the menu. The attributes returned are the current state values of the menu 
item ANDed with the attribute mask specified in mp2. It does not change any of the 
attributes of the menu item. This message will only query an item in the menu specified. 

mpl = SH0RT1FR0MMP(mp1 ) Position of item to find. 

SH0RT2FR0MMP (mpl) Reserved and set to zero. 

mp2 = Requested attributes mask. 

The return value is the current state of the attributes requested. 

This example queries the attributes of the menu item at position 2. We are only 
interested in the MIA_CHECKED and MIA_DISABLED attributes: 

USHORT usAttrs = WinSendMsg (hWndMenu, MM_QUERYITEMATTRBYPOS, 
MPFR0MSH0RT(2), MIA_CHECKED | MIA_DISABLED); 


MM SETITEMATTR— 0x0192 


This message is sent to set the current attributes of a menu item. Only those attributes 
specified by the attributes mask are modified by this message. 


mpl = SHORT1FROMMP(mpl) 
SH0RT2FR0MMP(mpl) 


mp2 - SH0RT1FROMMP(mp2) 
SH0RT2FR0MMP(mp2) 


Identifier of item to set. 
TRUE Include submenus in the 

search to find the item. 
FALSE Do not search submenus 

to find the item. 
Attributes mask. 
Attribute flags. 


The return value is TRUE if the attributes were successfully modified. 


This example sets the MIA_CHECKED flag of the menu item with identifier 0x201: 

WinSendMsg (hWndMenu, MM_SETITEMATTR, MPFROM2SHORT(0x201, TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 


2 m 
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MM_SETITEMATTRBYPOS—0x01 f6 
(UNDOCUMENTED MESSAGE) 

This message is sent to set the current attributes of a menu item specified by its position 
in the menu. Only those attributes specified by the attributes mask are modified by this 
message. This message will only set an item in the menu specified. 

mpl = SHORT 1 FROMMP (mpl ) Position of the item to set. 

mp2 = SHORT 1 FROMMP (mp2) Attributes mask. 

SH0RT2FROMMP (mp2) Attribute flags. 

The return value is TRUE if the attributes were successfully modified. 

This example sets the MIA_CHECKED flag of the menu item at position 2: 

WinSendMsg (hWndMenu, MM_SETITEMATTRBYPOS, MPFR0MSH0RT(2), 

MPFR0M2SH0RT(MIA_GHECKED,MXA_GHECKED ))\ 

MM_SETITEMCHECKMARK— 0x0210 
(UNDOCUMENTED MESSAGE) 

This message is sent to set the checkmark bitmap that is displayed for a menu item when 
it is in the checked or unchecked state. If a bitmap is not specified for one of the states, 
the system default bitmap is used. 

mpl = MPFR0M2SH0RT (menuitemID,bchecked) 
menuitemID 

bchecked TRUE 

FALSE 

mp2 = Bitmap handle. 

The return value is TRUE if the request is succesful. 

This example sets the checkmark for both the unchecked and checked state of the 
menu item with identifier 0x201: 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (0x201,FALSE), hbmUnchecked); 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARK, 

MPFR0M2SH0RT (0x201,TRUE), hbmChecked); 


ID of the menu item to set. 
Bitmap is for the checked 
state. 

Bitmap is for the unchecked 
state. 
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MM_SETITEMCHECKMARKBYPOS—0x0 Ifc 
(UNDOCUMENTED MESSAGE) 

This message is sent to set the checkmark bitmap that is displayed for a menu item speci¬ 
fied by its position in the menu. The checkmark can be set for both the checked or un¬ 
checked state. If a bitmap is not specified for one of the states, the system default bitmap 
is used. This message will only set an item in the menu specified. 

mpl = MPFR0M2SH0RT (position,bchecked) 

position Position of menu item to set. 

bchecked TRUE Bitmap is for the checked 

state. 

FALSE Bitmap is for the unchecked 

state. 

mp2 = Bitmap handle. 

The return value is TRUE if the request is succesful. 

This example sets the checkmark for both the unchecked and checked state of the 
menu item at position 2: 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARKBYPOSj 
MPFR0MSH0RT (2), hbmUnchecked); 

WinSendMsg (hWndMenu, MM_SETITEMCHECKMARKBYPOS, 

MPFR0MSH0RT (2), hbmChecked); 

MM_MATCHMNEMONIC—0x01ft) 
(UNDOCUMENTED MESSAGE) 

This message is sent within the menu code when the WM_CHAR message is being processed 
and the menu code is trying to find a mnemonic match for the character pressed. This 
message is not sent to the owner window, so you must subclass the menu window in order 
to receive this message. 

mpl = SH0RT1 FROMMP (mpl) Character to match. 

SH0RT2FR0MMP (mpl) Number of submenu levels to search. 

0 = none. 

1 = top-level (this menu). 

2 = top+first submenu. 

3 = top+first 2 submenus (etc.). 

-1 = all. 

mp2 = Pointer to hwnd of menu where match found. 
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The return value specifies both the index of the item in the menu that matched and 
the level of the match: 

MRFR0M2SH0RT(hwndmenu,index) 

In addition, *mp2 is updated to contain the window handle of the menu that con¬ 
tained the mnemonic. 

Menu Notification Messages 

The following is a list of the more important menu notification messages. This list is 
followed by a description on the use of the undocumented menu notification messages. 


Message 

Value 

Description 

WM_COMMAND 

0x0020 

Notification of menu selection. 

WM_SYSCOMMAND 

0x0021 

Notification of system menu 
selection. 

WM_HELP 

0x0022 

Notification of help item 
selection. 

WMJNITMENU 

0x0033 

Menu is about to become 
active. 

WM_MENUSELECT 

0x0034 

Menu item has been highlighted. 

wm_menuend 

0x0033 

Menu is about to be hidden. 

WM_DRAWITEM 

0x0036 

Draw the ownerdraw menu 
item. 

WM_MEASUREITEM 

0x0037 

Determine the height of menu 
item. 

WM_CONTROLHEAP 

0x0039 

Retrieve heaphandle for menu 
data. 

WM_MENUCHAR 

0x003f 

Non-mnemonic menu char 
pressed. 

WM_NEXTMENU 

0x004e 

Determine next menu to 
display. 

MM_PORTHOLEINIT 

0x0 lfb 

Submenu about to be displayed. 

WM_MENUHELP 

0x0433 

Help hook about to be called. 


WM.MENUCHAR— 0x003f 
(UNDOCUMENTED MESSAGE) 

This message is sent from the menu code to its owner when the WM_CHAR message is be¬ 
ing processed and the alphanumeric key pressed does not match any of the mnemonics 
in the displayed menu. It allows the application to specify which menu item should be 
selected in this case. 
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mpl = Window handle of menu currendy displayed 
mp2 = SH0RT1 FROMMP (mp2) Character. 

SH0RT2FR0MMP (mp2) Unused. 

The return value specifies how PM should deal with this invalid character: 

MRFROM2SHORT(0,0) Character is invalid (beep). 

MRFR0M2SH0RT (0,1) Cancel the menu. 

MRFR0M2SH0RT (position, 2) Select the menu item specified by 

position. 

Any other return code means to ignore the character and do nothing. Normally, this 
message is passed to WinDefWindowProc, which returns 0L. 

MM_PORTHOLEINIT— 0x01 fb 
(UNDOCUMENTED MESSAGE) 

This message is sent from the menu code to its owner just prior to summoning a pop-up 
menu. Upon return from the processing of this message, PM will again retrieve the 
submenu handle for the selected item. This allows an application to replace the submenu 
just prior to the submenu being displayed. 

mpl = SH0RT1 FROMMP (mpl) Position of submenu in the menu. 

SH0RT2FR0MMP (mpl) Attribute of the menu item. 

mp2 = Menu handle containing the item. 

The return code is ignored for this message. 





Introduction of GPI 

When programming for the PC first began, most graphics libraries were homegrown. 
Later, compilers added libraries of drawing functions. As useful as these were, they were 
somewhat limited in scope and in availability for various devices. Still later, with the 
development of operating systems that supplied graphical user interfaces, draw- 
v , ing functions were made a part of the operating system. 

OS/2 2.1 provides a rich set of functions, called drawing 
primitives, which may be used to render text and graphics on 
various devices. The drawing primitives are part of the device 
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independent functions in GPI (Graphics Programming Interface). GPI defines a high- 
level graphics programming library that an application can code to. In other words, the 
programmer no longer must be concerned with setting specific pixels on specific devices, 
rounding off errors, and other such matters; they are built into the operating system. 

The GPI programming model allows applications to use its 200-plus functions to 
output text and draw circles and arcs on any device. The functions of the library exist in 
the system DLL, PMGPI. GPI is actually a thin layer on top of the OS/2 graphics en¬ 
gine. The graphics engine is the component that contains the algorithms to render filled 
areas, lines, and arcs and to perform clipping. Between the graphics engine and the hard¬ 
ware exists another component called a presentation driver. Presentation drivers are written 
to support an API called by the graphics engine. It is this driver’s job to communicate the 
drawing requests to the hardware in a form that it can understand. When the presenta¬ 
tion driver receives a call from the graphics engine, that driver may take one of three actions. 
It may call the device directly, if it supports the primitive. It may further break the call 
into primitives that the device can understand, or it may pass the call back to the graph¬ 
ics engine to be broken down into yet simpler primitives. 

The relationships among an application, the PMGPI DLL, the graphics engine, and 
presentation drivers are shown in the following illustration in Figure 6.1. 


Figure 6.1. 

Relationship of PMGPI, 
graphics engine, 
presentation drivers, and 
hardware. 
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Presentation Spaces (PS) 

An application interacts with GPI through a presentation space handle, or PS handle. 
This PS handle is device-independent; that is, no physical device, not even the screen, is 
associated with its operation. It is a logical or virtual drawing space. The handle is a 32- 
bit value that represents an internal data structure that defines the attributes applied to 
graphics primitives. Attributes are settings that control the colors and styles used when 
drawing GPI figures. For example, the fill color and line styles are set as attributes. All 
GPI functions require a PS handle. Associated with a device-independent PS is a device¬ 
specific 32-bit context handle. Device contexts (DCs) are the link between GPI and the 
physical device it represents. It is the device context that can be queried for device spe¬ 
cific values such as resolution, size, and capabilities. The resolution, size, and so forth are 
determined by the specific physical characteristics of a device. 

Types of Presentation Spaces 

A PS may be retrieved or created in several ways. The easiest way is by calling the 
WinBeginPaint or WinGetPS functions. Although both return a PS handle, they are 
designed to be called at different times during program execution. When portions of your 
application’s drawing area become invalid (require repainting), PM will place a WM_PAINT 
message in your application’s queue. Calling WinBeginPaint in response to the paint 
message returns a PS handle that is clipped to the region that needs to be updated. This 
means that any drawing your application does will affect only the portion of the window 
that actually requires updating. For example, if a pop-up window from another applica¬ 
tion is moved over your window and then moved away, only a small portion of your 
window must be redrawn. On the other hand, when you call WinGetPS, the PS that you 
receive has no clipping region defined and enables you to draw on the entire client area. 

Three types of PS handles exist, cached micro, micro, and normal. The cached micro 
PS offers the best performance and uses the least system resources of the three. It is drawn 
from a set of PS handles that are maintained by the window manager (PMWIN). These 
PS handles are available for short-term application use and may be used only on the dis¬ 
play device. Retained graphics may not be used in a cached micro PS. Retained graphics 
is a type of graphic output. Primitives are stored in a segment that can be edited. In 
nonretained output, after a function is called, it is lost and must be called again to re¬ 
create the output. 

A cached micro PS may be “checked out” by calling the WinGetPS, WinGetScreenPS, 
or WinBeginPaint functions. Before returning to the application, the attributes are reset 
to the system default values. After use, the PS is returned to the window manager by calling 
the WinReleasePS or WinEndPaint functions. Cached micro presentation spaces are best 
suited to windows that are updated frequently and don’t require a large number of 
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customized attributes. A good example would be a control window that updates a rect¬ 
angle to indicate percentage of completion on an operation when a notification message 
is received. This is something like the thermometer control that we will show you how to 
build later in this chapter. 

Unlike the cached micro PS handle, a micro PS handle is not automatically associ¬ 
ated with the display device. You must associate it with a device context from a display 
window, memory, or printer. This enables you to print or create bitmaps in memory in 
addition to drawing directly to a window. When associated with a device, a micro PS 
may not be reassociated with any other device-context. Like the cached micro PS, it does 
not support retained graphics. A micro PS is created by calling the GpiCreatePS func¬ 
tion. One of the parameters to the function is a device-context handle with which to 
associate the created PS. For display devices, the DC handle for the window may be re¬ 
trieved by calling the WinOpenWindowDC function. The WinOpenWindowDC takes a win¬ 
dow handle as its only parameter and returns a device-context handle that is valid for the 
life of the window. WinOpenWindowDC will fail after the first call and should be called 
only once for each window. After a window DC has been opened, that DC may be que¬ 
ried with the WinQueryWindowDC function. For devices other than the display, device 
contexts must be created by calling the DevOpenDC function. This function will be dis¬ 
cussed in greater detail later in this chapter. 

The third type of PS, normal, is also created by using the GpiCreatePS function. As 
with the micro PS, it must be associated with a device context; however, it may be reas¬ 
sociated with other device contexts. Normal PSs are the only types that support retained 
graphics. By using the GpiAssociate function, a normal PS may be reassociated from 
one window DC to another, or from a window to a printer DC. The problem with the 
GpiAssociate function is that a PS may not be directly associated from one DC to an¬ 
other. The association with the current DC must first be broken by calling the 
GpiAssociate function with NULL as the new DC handle. Then the PS may be asso¬ 
ciated with a new DC. When the GpiAssociate function is called, attributes set in that 
PS are reset to the default value by the equivalent of the GpiResetPS function call. For 
the attributes set into the PS to be retained, they must be queried and then reset into the 
PS after the association with the new device context is done. OS/2 2.1 will allow direct 
association from one device context to another; however, the attributes will still be reset 
to the default values. 

The big advantage that either the micro or normal PS has over the cached micro is 
the capability to preserve attribute settings. When set, attributes will remain current until 
changed by a function like GpiSetAtt rs or reset by GpiResetPS. This convenience comes 
at the expense of performance, however. The GpiCreatePS function is expensive in terms 
of execution time and system resources. The micro and normal PS are best utilized in the 
main window or windows of an application where most of the drawing occurs. 


252 



Chapter U Presentation Spaces and Drawing 


With the exception of an application with an MDI interface, most applications do 
nearly all their drawing in a single window. If a micro or normal PS handle is used for 
this window, the overhead of its creation occurs at program start-up. During program 
execution, attributes remain constant until changed by the application. This can be ex¬ 
tremely useful for resources such as fonts that must be created and set into the same PS, 
especially because creating and setting these resources requires so much overhead. Win¬ 
dows with micro or normal PS handles should pass that handle to the Win Beg in Paint 
function when processing the WM_PAINT message. This will cause the current update re¬ 
gion to be set into the supplied PS, but leave the attributes unchanged. The PS should be 
freed when your application terminates or no longer requires it. Before freeing the PS, 
the association with the device context must be broken by calling GpiAssociate with 
NULL as the second parameter. The PS then may be freed by calling the GpiDestroyPS 
function. A cached micro PS may still be retrieved for a window that has a micro or nor¬ 
mal PS associated with it by calling WinGet PS or Win Beg in Paint with NULL as the second 
parameter. A cached micro PS will have the default PS setting, which may be easier to 
use than resetting all the attributes of the main PS to the default values. 

WM_PAINT & WM_ERASEBACKGROUND 

The WM_ERASEBACKGROUND message is sent to a client window by the frame window as 
part of its normal paint processing. The mpl parameter will contain the PS handle for the 
frame that may be used to draw in the client area. Because this PS was obtained when the 
frame window called WinBeginPaint, it will enable you to draw in areas outside your 
client window. Be aware that the 0,0 point may have shifted down and to the left based 
on the system size of sizable window borders. If you return TRUE for this message, the 
frame window will fill the invalid portion of the client window with the current window 
background color. If you return FALSE, the frame window assumes you have handled 
the paint and takes no further action. 

Because the WM_ERASEBACKGROUND message is sent only when the frame is invalidated, 
using it to do any painting will provide poor results. Let’s say, for example, that you want 
the client area to have a grid drawn as its default workspace. If you fill the client window 
and draw a grid after receiving the WM_E RASE BACKGROUND and paint the objects on the 
grid when you receive the WM_PAI NT message, some problems can occur. When the frame 
window is invalidated or sized, the scheme described previously will work fine. If, 
however, a window smaller than the frame is moved over your client window and then 
minimized, the frame will not repaint, and your application will not receive the 
WM_ERASEBACKGROUND to draw the grid. It is recommended that any background paint¬ 
ing be done while processing the WM_PAINT message. 
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Summary of Presentation Space Functions 

In the following text is a summary of the functions used to create and destroy presenta¬ 
tion spaces of various types. The function usage is divided into cached and non-cached 
sections. 

Cached Micro Presentation Spaces 

KPSWinGetPS (hWnd) 


HWND 

hWnd 

Window handle to retrieve the cached micro PS 
handle for. You may use HWND JDESKTOP to 
retrieve a PS for the entire screen. 

HPS 

hPS 

If successful, the return value will be a PS that has 
been associated with the window device context. 
NULL is returned if a failure occurs. The returned 
PS is always reset to the default values. (See Table 
6.1 for a complete list of default values.) 


hPS WinBeginPamt(hWnd,hPS,pRectl) 


HWND 

hWnd 

Window handle for which to retrieve the cached 
micro PS handle. 

HPS 

hPS 

Use NULLHANDLE. 

PRECTL 

pRect 

Pointer to a RECTL structure that will contain the 
smallest bounding rectangle that contains the 
update region. Values are always in window 
coordinates. 

HPS 

hPS 

If successful, the return value will be a PS that has 
been associated with the window device context. 
NULL is returned if a failure occurs. The returned 
PS is first reset to the default values, and then the 
update region is set as the clipping region in the PS. 

Micro or 

Normal Presentation Spaces 

hPS GpiCreatePS 

(hAB,hDC,pSizel,!Options) 

HAB 

hAB 

Handle to anchor block returned from the 
Winlnitialize function. 
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HDC 


PSIZEL 


LONG 

Units 


Format 


Type 


Mode 


hDC 


pSizel 


lOptions 


Device-context handle to associate with the 
PS to be created. If lOptions contains the 
GPIT_MICRO or GPI_ASSOC flags, the 
DC is required. 

Pointer to a SIZEL structure that defines the size of 
the created PS’s page. If an hDC value is supplied, 
the page size is automatically set based on the 
dimensions of the device. 

Bit flags used to define the units, format, type, and 
mode of the created PS. 

Defines the meaning of each unit in a PS page: 


PU_PELS 

PUJLOMETRIC 

PU.HIMETRIC 

PUJLOENGLISH 

PU_HIENGLISH 

PU_TWIPS 

PU_ARBITRAY 


One unit equals 1 pel. 

One unit equals . 1 mm. 

One unit equals .01 mm. 

One unit equals .01 inches. 
One unit equals .001 inches. 
One unit equals 1/1440 inch. 
Application defined. 


Format to be used for storing coordinates inter¬ 
nally: 


GPIFJLONG Coordinates are stored as 

4-byte integers. 

GPIF_SHORT Coordinates are stored as 

2-byte integers. 

GPIF_DEFAULT Equivalent to GPIF_LONG. 

Presentation space type to create: 

GPIT_MICRO A micro PS is created. 

The GPIA_ASSOC flag 
must be set, and the 
hDCparameter must contain 
a device context to associate 
the created PS with. 

GPIT_NORMAL A normal PS is created. 


Association action to be taken: 


GPIA.ASSOC Associate the created PS 
with the supplied device 
context. hDC must contain 
a valid device context. 
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Mode GPIA_NOASSOC Do not associate the created 

PS with a device context. 

hPS WinBeginPaint(hWnd,hPS,pRectl) 


HWND 

hWnd 

Window handle to retrieve micro or normal PS 
handle for. 

HPS 

hPS 

The PS handle returned from GpiCreatePS. 
NULLHANDLE may be used to retrieve a micro 
cached PS. 

PRECTL 

pRect 

Pointer to a RECTL structure that will contain the 
smallest bounding rectangle that contains the 
update region. Values are always in window 
coordinates. 

HPS 

hPS 

If successful and a presentation space was supplied 


as the second parameter, the return value will be 
the supplied PS. If NULLHANDLE was passed as 
the second parameter, the return value will be a 
micro cached PS. In either case, the current update 
region set as the clipping region is the returned PS. 

GpiAssociate(hPS,hDC) 

HPS hPS The PS handle to reassociate. 

HDC hDC The device context to associate the hPS with. In 

OS/2 2.0, you may not directly associate a PS 
from one DC to another. The GpiAssociate 
function must be called two times, first with 
NULLHANDLE as the second parameter and 
second with the DC handle to associate the 
presentation space with. Attributes in the PS 
are reset to the defaults. 

GpiDestroyPS (hPS) 

HPS hPS The PS handle to be destroyed. It must first be 

disassociated from the current PS by calling the 
GpiAssociate function with a NULL hDC. 
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Device Contexts 

As mentioned previously, the device context is the link between a PS and the physical 
device it represents. Like presentation spaces, a device context is identified by a handle. 
Using this handle, the resolution, device type, and capabilities of the physical hardware 
can be retrieved. An entire API (called Device functions or DEV for short) is devoted to 
interacting with device contexts. We will look at these functions shortly, but first we 
examine window device-context handles. 

Device contexts can be retrieved or created in several ways. For windows, a DC is 
created by calling the WinOpenWindowDC function and passing it the handle of the win¬ 
dow for which a device-context handle is to be opened. If successful, the device-context 
handle returned is constant for the life of the window regardless of the type of PS used in 
the window. There is no equivalent WinCloseWindowDC function to free the DC handle 
when it is no longer required. It will be freed automatically when the window is destroyed. 
WinOpenWindowDC should be called only once for a given window; however, if you lose 
track of the window DC handle, you can use the WinQueryWindowDC function after a 
DC has been opened. In fact, you can create your own function called WinGetDC, which 
does all the work for you. 

For example, observe the following: 

HDC APIENTRY WinGetDC(HWND hWnd) 

{ 

hDC hDC 

if (!(hDC = WinQueryWindowDC(hWnd))) 
hDC = WinOpenWindowDC(hWnd); 

return (hDC); 

} 

If the DC for the window has already been opened, the WinQueryWindowDC will re¬ 
turn the DC; otherwise, a DC is opened for this window. Using this function, you never 
need to worry about the state of the window device context. 

For output devices other than a window, device contexts must be created by using 
one of the functions from the device API. The DevOpenDC function will create device 
contexts for use with metafiles, bitmap drawing, and device output. A device context 
should be opened when output is intended for a device other than a window. The 
DevOpenDC function takes the following parameters: 

DevOpenDC (hAB,lType,pszToken,ICount,pdod,hDC) 

FfAB hAB Handle to anchor block returned from the 

Winlnitialize function. 
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Type This parameter identifies the type of device context 

to be created. 

OD_MEMORY 

Creates a device context in which a bitmap may 
be set to draw “off screen” and then bit’d to a 
window or print device. 

OD_METAFILE 

Creates a device context that can be used to 
create memory or disk metafiles 
O D_METAFILE_N O QUERY 
Creates a device context that can be used to 
create memory or disk metafiles, but that cannot 
be used for querying attributes. 

OD_QUEUED 

Creates a device context for a printer or plotter 
that will use the print spooler to queue and send 
print jobs to physical print device. 

OD_DIRECT 

Creates a device context that will output directly 
to a physical port. This option is a holdover 
from previous versions of OS/2 and should not 
be used by applications when performing 
normal print operations. 

OD_INFO 

Creates a device context that may be queried for 
device-specific information and drawn into, but 
that will cause no output to occur. This DC 
type should be created when you need to know 
device information but are not currently 
printing. 

pszToken Pointer to a null-terminated string that is an entry 
in an initialization file. Applications will generally 
use to indicate that initialization data should be 
taken from the DEVOPENDATA passed to the 
function. 

ICount A long that identifies the number of parameters 
initialized in the DEVOPENDATA structure. 
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PDEVOPENDATA 

pdod 

Pointer to a DEVOPENDATA structure 
that provides the information required to 
create the DC. 

HDC 

hDC 

A device-context handle with which to 
make the new device context compatible. 
If NULLPiANDLE is used, compatibility 
with the display device is assumed. 


If successful, the DevOpenDC function will return a device-context handle that may 
then be associated with a PS. A device context must be associated or linked with a PS 
before output can occur on that device. Chapter 11, “Printing,” will look in depth at 
information and print device contexts. 

Device Capabilities 

After you have a device context, you can query the device to determine its capabilities by 
using the DevQueryCaps function. You may query one or all the values from the device 
including device resolution, color support, I/O support, and graphics capabilities. If you 
are using a feature of GPI not supported on all devices, utilize the DevQueryCaps func¬ 
tion to determine whether the device supports it. You can also use this function to deter¬ 
mine whether the device has built-in support for something PM is handling. For example, 
the following code determines whether the device can directly support wide lines outside 
a path: 

DevQueryCaps (hDC,CAPS_ADDITIONAL_GRAPHICS,1,lAddGraphies); 
if (lAddGraphic & CAPS_COSMETIC_WIDELINE_SUPPORT) 
bUsePaths = FALSE; 

Coordinates 

A coordinate system is a method of positioning items in an n-dimensional space. GPI 
coordinates are pairs of longs that define a position in a two-dimensional drawing space. 
An X value defines a position along the horizontal axis, and a Y value defines a position 
along the vertical axis. The point where the X- and Y-axes intersect defines the origin. 
The default origin (0,0) for a window PS is in the lower-left corner of the screen, with X 
values increasing as you move to the right and Y values increasing as you move toward 
the top of the screen. In each PS, a current coordinate position is maintained. Many GPI 
primitives use the current position as the location to begin drawing from. The current 
position may be set or retrieved by using GpiMove and GpiQueryCurrenPosition, 
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respectively. In some cases, GPI primitives update the current position. GpiPartialArc, 
a function we use later in this chapter, updates the current position to the last point drawn 
in the arc. 

Default Presentation Space Attributes 

When a PS is created, associated with a new device context, or when a cached micro PS 
is retrieved, the attributes are set to the default system values. These defaults define such 
things as the current position, clipping paths, and the colors used when filling and out¬ 
lining boxes and ellipses. The default attributes may also be reset in a PS by calling the 
GpiReset function. Table 6. 1 found later in this chapter contains the default PS attributes. 
The term default may be misleading here because PM enables you to change the default 
attributes for a PS by calling the GpiSetDef Attrs function. Because this function re¬ 
quires a handle to a PS, the default may be changed only for an existing PS, not for those 
created or retrieved in the future. Although you may change the default fill color from 
white to blue in the PS you created for your application, you cannot change the default 
fill color for all future PSs created by your process. Generally, changing the default at¬ 
tributes in a PS is not recommended even if your application modifies every attribute. 
All the potential benefits gained by changing these values is lost when they are reset with 
the GpiResetPS or GpiAssociate functions. A more efficient method is to maintain 
and set attributes as bundles. 


BUNDLES 

You are probably familiar with GPI “set” functions that modify attributes in a PS. For 
example, GpiSetBackColor will modify the background color used for fills, lines, and 
text. The most powerful function in the GPI attribute-setting arsenal, however, is also 
probably the one most overlooked. The GpiSetAttrs function enables you to set or re¬ 
set single or multiple values in a bundle with a single function call. A bundle is a data 
structure that your application can use to set, query, and store drawing attributes. PM 
defines a set of five bundle structures. These define attributes that affect drawing across 
drawing primitives. They are as follows: 


Type 

AREA 

CHARACTER 

IMAGE 


GPI Functions Affected 

The area bundle defines the current fill, color, and pattern 
used in functions such as GpiBox. 

The character bundle defines character attributes that affect 
the size, color, angle, and type of font used when text is 
output through functions such as GpiCharString. 

The image bundle defines the color and mix mode used in 
monochrome bitmaps output by functions such as GpiBitBlt. 
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Type GPI Functions Affected 

LINE The line bundle defines the style and color of lines drawn as 

the outline of filled objects by functions such as GpiBox. 
Functions such as GpiPartialArc that draw lines but do not 
fill areas also use attributes in the line bundle. 

MARKER The marker bundle defines the color and style used when 

drawing markers with such functions as GpiPolyMarker. 

The GpiSetAttrs function takes a pointer to a bundle structure that has been ini¬ 
tialized by the caller. Based on the flags set, you can set one or all the values in a PS to a 
new value or to their defaults. The GpiSetAttrs function is defined as follows: 

GpiSetAttrs (hPS,IPrimType,ulAttrMask, 
ulDe£Mask,pBundle) 

HPS hPS Handle of the PS in which to change the attribute. 

LONG IPrimType Identifies the bundle type to modify. It may be one 

of the following: 

PRIM_AREA 

PRIM_CHAR 

PRIM.IMAGE 

PRIMJLINE 

PRIM_MARKER 

ULONG ulAttrMask Contains one or more flag values that indicate 

which attributes to set. The appropriate fields in the 
bundle structure must be initialized accordingly. 

ULONG ulDefMask Contains one or more flags that indicate which 
attributes to reset to their default values. The 
corresponding flag must be set in the ulAttrMask. 

PBUNDLE pBundle Pointer to a bundle of IPrimType. 

The flags in the ulAttrMask indicate which fields have been initialized in the bundle 
and should be changed in the PS. To set the default value, you must set the flag of the 
desired attribute in both the ulAttrMask and ulDefMask parameters. The field in the 
bundle need not be initialized because it is ignored when the default is reset. The default 
may not be set by passing the default parameter in the field of the bundle. For example, 
assuming pAB is a pointer to an area bundle, the correct way to reset the area bundle 
background color is as follows: 

GpiSetAttrs(hPS,PRIM_AREA,ABB_BACK_COLOR,ABB_BACK_COLOR,pAB); 


201 



Real-World Froqrammmq for 


OS /2 2.1 


Although the two following lines look good, they won’t work as intended: 
pAB->lBackColor = CLR_DEFAULT; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_BACK_COLOR,0,pAB); 

All bundle types have four attributes in common: each has a foreground and back¬ 
ground color, and each has a foreground and background mix mode. The foreground 
color defines the color used when drawing the primary or foreground of the primitive. 
What actually comprises the foreground varies from bundle to bundle, but it is best de¬ 
scribed as the main component of the primitive. For example, the foreground color in 
the character bundle defines the color of the characters that are output. For pattern sets, 
the foreground color is the color of the pattern lines. The background color defines how 
the remainder of the primitive is colored. In the character bundle, the background color 
is used to fill the space behind the characters. For pattern sets, the space between the actual 
pattern is defined by the background color. The mix mode for both foreground and back¬ 
ground defines how their colors are combined with the color of the destination. The fore¬ 
ground mix mode may be set to one of 16 values, including overpaint and XOR. The 
background mix may be set to only one of four values. 

Four functions exist for setting one of the previous four values in all bundles simul¬ 
taneously, the GpiSetColor, GpiSetBkColor, GpiSetMix, and GpiSetBackMix. When 
an attribute must be set in all bundles, it is more efficient to set it by using one of the 
generic functions such as GpiSetColor. Rarely are all foreground colors set to the same 
value. In cases when they are, the GpiSetAttrs function should be used in place of a 
more global function. For example, assuming all variables are defined and initialized, the 
following will work: 

GpiSetColor (hPS,CLR_RED); 

GpiBox(hPS,DR0_FILL,ptl1,0,0); 

GpiSetColor (hPS,CLR_BLUE); 

GpiBox(hPS,DR0_FILL,pt12,0,0); 

The GpiBox function will use only the foreground color set in the area bundle 
(assuming a solid pattern fill). The foreground color set in the other four bundles are 
unused. Using the GpiSetAttrs function is much more efficient: 

ab.lColor = CLR_RED; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_C0L0R,0,pAB); 

GpiBox(hPS,DRO_FILL,ptll ,0,0); 
ab.lColor = CLR_BLUE; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_C0L0R,0,pAB); 

GpiBox(hPS,DR0_FILL,ptl2,0,0); 

With the exception of the image bundle, the four remaining bundles have attributes 
other than color and mix mode that may be modified. We will examine the additional 
fields in those bundles. 
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Area Bundle 

The area bundle defines the color and pattern for filled areas. The area may be a simple 
rectangle or a complex polygon. When wide lines are drawn, they are filled with the cur¬ 
rent area bundle attributes. The area bundle has three additional fields that may be set to 
define the fill area. 

usSet 

The usSet parameter enables you to set a local identifier for a bitmap that will be used in 
the fill area. Monochrome bitmaps will use the foreground area bundle color for the fore¬ 
ground (black bits) of the bitmap. The background color will be used for the background 
(white bits) of the bitmap. Color bitmaps are not affected by the area bundle foreground 
and background colors. 

usSymbol 

The usSymbol parameter is used to specify a solid fill or one of the PM-defined hatch 
patterns for the fill area. Hatch patterns are intended to be a device-independent nonsolid 
fill type. Although the display and some printers may have the capacity to render bitmaps, 
plotters do not. Hatch patterns are implemented by all devices, including plotters. The 
patterns consist of horizontal, diagonal, and cross hatched lines of varying densities. 

ptlRefPoint 

The ptlRefPoint is an X and Y location that a bitmap or pattern fill is aligned to within 
the PS. It may be thought of as the point that bitmaps and patterns are “tiled” around. 
The entire area is filled regardless of the point supplied, even if that point is outside the 
fill area. The default pattern reference point is 0,0. If the reference point is modified, it 
should be modified for all subsequent painting. Failure to do this may result in a mis¬ 
alignment of the pattern or bitmap in a filled area after a partial repaint of that area. 


CHARBUNDLE 

As mentioned previously, the foreground color in the character bundle defines the color 
used when filling characters, whereas the background color will fill the space behind the 
characters. The default background mix mode, however, is BM_LEAVEAL0NE, which re¬ 
sults in no background fill. The character bundle has nine additional fields that may be 
set to control the font, character size, and orientation when outputting text. Chapter 7, 
Creating and Manipulating PM Fonts and Text,” will discuss these fields in more 
detail: 
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usSet 

Local identifier that represents a logical font. 

usPrecision 

Character mode. 

sizfxCell 

Defines a character cell or box used in scaling outline fonts. 

ptlAngle 

Point that defines a new end point of the line which determines 
character baseline. 

ptlShear 

Point that defines a new end point of the line which determines 
how a character box is slanted relative to the baseline. 

usDirection 

Flag that defines the direction characters are drawn relative to 
the baseline. 

usTextAlign 

Flag values that define how a text string is aligned relative to the 
current position. 

fxExtra 

Specifies the amount of additional space added or subtracted 
between characters when a text string is output. 

fxBreakExtra 

Specifies the amount of additional space added or subtracted to 
the break character. The space character is most often the break 
character. 


LINEBUNDLE 

The line bundle affects primitives that output lines or that outline a filled area. For ex¬ 
ample, the GpiBox function uses the current line bundle attributes if the DRO_OUTLINE 
or DRO_OUTLINEFILL fill flags are used. The DRO_OUTLINE tells the function to leave the 
interior of the box unchanged and to outline it with the current line bundle attributes. 
DRO_OUTLINEFILL causes the box to be filled with the current area bundle attributes before 
being outlined. When the line style is other than solid, the background color will not be 
used to fill the gaps in the line as expected. To change the “background” of a dashed or 
dotted line, you must first draw a solid line with the foreground color set to the desired 
background color, and then draw the dashed or dotted line. The line bundle has five 
additional fields that define line attributes. 


fkWidth 

This parameter defines the width of cosmetic lines. Cosmetic lines are those not drawn 
as a result of a stroked path. Only two widths are supported, normal and thick. Normal 
widths are one device unit, and thick widths are two device units. 

lGeomWidth 

This field defines the geometric width of a line. The geometric width is used by GPI when 
drawing a “wide line” in a stroked path. When a primitive that renders lines is drawn in 
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a path and the path is stroked, the normal line width is converted to a wide line. The new 
wide line is filled as an area; in fact, it is filled with the current area bundle fill attributes. 
This allows wide lines to be filled with patterns and bitmaps. The width is actually one 
pel wider that the lGeomWidth value. 

ulType 

ulType defines the line style used when drawing cosmetic lines. The default type is solid; 
however, several dotted and dashed styles along with invisible may be selected. The in¬ 
visible line style can be used to update the current position in the PS without affecting 
the display. For example, the GpiPartialArc primitive begins drawing at the current 
location. Setting the line type to invisible and drawing the arc will cause the current 
position to be updated to the last point on the arc, but no screen or printer drawing will 
occur. This will be demonstrated later in this chapter. Geometric lines are not affected 
by this value. 

ulEnd 

This field defines the line end style for geometric lines. This style determines whether the 
end of the line should be rounded, flat, or square. Cosmetic lines are not affected by this 
setting. 

uljoin 

This field determines the appearance of connected lines drawn in a path. A connected 
line is one in which starting and ending points of separate primitives occur at the same 
point. Cosmetic lines are not affected by this setting. 

MARKERBUNDLE 

A marker is a symbol or character that is drawn centered over a given point. PM supplies 
a set of default markers that are often used to mark points on a chart or graph. Included 
in that set are a diamond, square, dot, and various stars. 


usSet 

The usSet field contains a local identifier that represents a logical font. This allows an 
application to use a character from any font as a custom marker. The usSymbol defines 
the character in the font to use as the marker. 



Real-World Programming 


for OS /2 2.1 


usSymbol 

If the default marker set is used, this field contains the ID (identification) of one of the 
system-supplied markers. If a custom marker set is set, this field will contain the code 
point (1-255) of the character to be used as the marker. For example, you could use a 
capital M as a custom marker. 

sizefxCell 

If the logical font defined by the usSet field is an outline font, this parameter defines a 
character cell or box used in scaling the character. 

Color Models 

In all the bundles discussed previously, you are able to set a foreground and background 
color. In PM, colors may be specified in one of two methods, as a color table index that 
identifies an RGB value or as an RGB value. An RGB value is a representation of a color 
based on the red, green, and blue content in that color. In the default PS, a logical color 
table is created by PM. To reference colors from this table, you use one of the predefined 
CLR_ values. This is often referred to as indexed mode. You may create your own logical 
color table or modify an existing one with the GpiCreateLogColorTable function. An 
existing table may be modified by querying the current color table with the 
GpiQueryLogColorTable, changing the desired values, and re-creating a new logical color 
table with the GpiCreat eLogColorTable. You may also use this function to switch into 
RGB mode. RGB mode enables you to supply RGB color values as the color value when 
one is required. Switching into RGB mode can be done as follows: 

GpiCreateLogColorTable (hPS,LCOL_RESET,LC0LF_RGB,0,0,NULL); 

Resetting the default color table is done as follows: 

GpiCreateLogColorTable (hPS,LCOL_RESET,LCOLF_INDRGB,0,0,NULL); 

Line and Arc Primitives 

In the following text is a summary of some of the more important GPI drawing func¬ 
tions. This certainly is not an exhaustive list because OS/2 has a great many drawing 
functions. This list, however, will give you a good place to start learning. 

Only the GpiBox and GpiFullArc functions are capable of filling their interiors. In¬ 
terior fill and figure outline methods, for both functions, are set by a fill control param¬ 
eter. The figures may be filled, outlined, or both. The control flags are as follows: 
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DRO_OUTLINE Outline the ellipse or box. 

DRO_FILL Fill the interior of the ellipse or box. 

DRO_OUTLINEFILL Outline and fill the ellipse or box. 

The current area bundle attributes determine the fill for rectangles and ellipses. The 
cosmetic line attributes are used to draw the boundary for all line and arc primitives and 
to outline boxes and ellipses when the fill control flag is set to DRO_OUTLINE or 
DRO_OUTLINEFILL. 

Some of the more useful functions are listed here: 


GpiBox 

GpiFullArc 

GpiLine 

GpiPartialArc 


GpiPointArc 

GpiPolyFillet 


GpiPolyFilletSharp 

GpiPolyLine 

GpiPolySpline 


Draws a rectangle or rounded rectangle from the current 
position to a new point supplied to the function. The 
figure may be filled, outlined, or both. 

Draws an ellipse (or circle) using the current arc 
parameters around the current position. Arc parameters 
define extent in the X and Y directions and shears. 

Draws a straight line from the current position to a 
supplied end point. 

Draws a portion of an ellipse (or circle) using the current 
arc parameters based around a supplied center point 
from the current position. Arc parameters define extent 
in the X and Y directions and shears. A starting angle 
and sweep angle define the starting and ending points of 
the arc. 

Draws an arc from the current position through a second 
point to an end point using the current arc parameters. 
Draws a curved line (fillet) as a series of connecting arcs 
starting at the current position based on an array of 
points defining straight lines. Each arc is tangent to the 
midpoint of the supplied line segments. The end point is 
the same as the last point in the array. 

Draws one or more curved lines (fillets) using a sharp¬ 
ness value that will cause each curve to approximate an 
ellipse, hyperbola, or parabola. 

Draws one or more connected straight lines from the 
current position. 

Draws one or more connected Bezier splines from the 
current position. 
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Drawing a Thermometer 

In Chapter 10, “Dynamic Link Libraries,” we will create a custom thermometer control 
to show the amount of memory resources being used. This is a simple illustration of a 
thermometer filled with an area of color that depends on a ratio that makes sense in the 
application. Before a thermometer control can be created, a function to draw a thermom¬ 
eter must be written. 

Before coding can begin, we must define the appearance of the thermometer and the 
GPI function used to draw it. A thermometer typically has a round bulb attached to a 
stem with a rounded top. Because real thermometers are made of glass, they are transpar¬ 
ent with the exception of the mercury or other liquid that fills it. In our thermometer, 
the mercury will rise from the bulb to the top of the stem as the application-defined ratio 
increases. 

To maintain a 3-D look, the outline of our thermometer will be drawn in white and 
shades of gray. This gives the appearance of a light source in the upper-left corner of the 
screen. The thermometer will therefore be consistent with the other default control win¬ 
dows such as pushbuttons. The thermometer will be drawn by using two functions, 
DrawThermometer and DrawTemperature. The first will draw the outline, bulb fill, and 
highlights. The second will draw the mercury in the stem. The temperature may then be 
drawn independent of the thermometer. The thermometer will be drawn within the sup¬ 
plied rectangle. If the rectangle is enlarged, the thermometer will be scaled with it. This 
leaves it up to the caller to define its size and position. Figure 6.2 shows the thermometer 
and the GPI primitives used to create it. 

The outline could be drawn with GpiPolyLine. Calculating the points of the out¬ 
line and the color transitions, however, would be too much trouble. The thermometer is 
best drawn as a series of lines and partial arcs. The bulb will be drawn first because the 
starting and ending point of its partial arc defines the starting location of the vertical lines 
that make up the stem. After some experimenting, we decided the bulb would occupy 25 
percent of the bounding rectangle. The bulb rectangle is calculated, and the arc param¬ 
eters are set. The arc parameters actually form a 2x2 matrix that scales and shears partial 
and full arcs (see Figure 6.3). 

The IP parameter scales the ellipse in the X direction, whereas the IQ parameter scales 
it in the Y. The values are set to half the width and half the height of the rectangle bounding 
the bulb, respectively. The 1R and IS parameters define shearing and are set to the de¬ 
fault values: 

arcparms.IP = (BulbRectl.xRight - BulbRectl.xLeft) / 2L; 
arcparms.lQ = (BulbRectl.yTop - BulbRectl.yBottom) / 2L; 
arcparms.1R = 0L; 
arcparms.lS = 0L; 

GpiSetArcParams(hPS 3 (PARCPARAMS)&arcparms); 
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Figure 6.2. 
Thermometer design. 



Figure 6.3. 

Arc parameters. 



Arc with no shearing 
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Figure 6.3. 
continued 



Arc with shearing 


The center point of the arc is established based on the bulb rectangle and the X and 
Y scaling values: 

lPtCenter.x = BulbRectl.xLeft + arcparms.lP; 
lPtCenter.y = BulbRectl.yBottom + arcparms.lQ + 1; 

The arc for the bulb must be drawn in two pieces; the highlighted side on the left will 
be drawn in white followed by the shaded side. The light source and the start angle for 
the first arc of the bulb will be at 120 degrees. The highlighted arc will continue for 90 
degrees. Before the first arc can be drawn, we must establish the current position as the 
first point on the arc. This must be done because the GpiPartialArc function will draw 
a line from the current position to that point resulting in a stray line. To do this, set the 
line type to invisible and draw an arc with a start angle of 120 degrees and a sweep angle 
of zero: 

fxStartAngle = MAKEFIXED(120,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS 5 PRIM_LINE 5 LBB_TYPE 5 0 3 (PBUNDLE)&lb); 

GpiPartialArc(hPS,&lPtCenter,MAKEFIXED(1,0) 3 fxStartAngle 3 MAKEFIXED(0 3 0)) 
GpiQueryCurrentPosition(hPS 3 (PPOINTL)&lStartPt); 

After the arc is drawn, the current position is queried and retained for drawing the 
left side of the thermometer stem. When the current position is established, the line type 
is reset to solid, the color is changed to white, and the arc is drawn with a sweep angle of 
90 degrees: 

fxSweepAngle = MAKEFIXED(90,0); 
lb. IColor = CLRJVHITE; 
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lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1 3 0) 3 fxStartAngle 3 fxSweepAngle); 

The current position is now the last point on the arc, so the shaded portion of the arc 
can be drawn without resetting the current position. After drawing the shaded portion of 
the bulb, the current position is saved for drawing the right side of the stem. When the 
exterior of the bulb is drawn, the interior is filled. This is done now for two reasons. First, 
all the values needed to draw the full arc have been calculated. The center point is the 
same, and the X and Y arc scaling values can be reduced to leave a transparent gap be¬ 
tween the outline and the mercury. Second, the bulb will always be drawn full regardless 
of the temperature: 

arcparms.lP -= 4; 
arcparms.lQ -= 4; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
ab.lColor = IColor; 

GpiSetAttrs(hPS 3 PRIM_AREA 3 ABB_COLOR 3 0 3 (PBUNDLE)&ab); 

GpiMove (hPSj&lPtCenter); 

GpiFullArc(hPS,DRO_FILL,MAKEFIXED(1,0)); 

The bulb is filled by using the GpiFullArc function and the DRO_FILL flag. The ellipse 
will be filled with the caller-supplied color set into the area bundle. For a more 3-D 
effect, two reflections are drawn on the bulb. They are drawn by reducing the X and 
Y scaling factor and drawing a partial arc in white starting at 120 degrees and sweeping 
for 90 degrees. 

The sides of the stem are then drawn by using the GpiLine function. The left side is 
drawn in white and the right in dark gray. After drawing the sides, the rounded top is 
drawn with two partial arcs as was done for the bulb. The code to draw the outline and 
the bulb for the thermometer will be put in the DrawThermometer function: 

DrawThermometer (hPS,pRectl,IStyle,IColor 3 IBackColor,IPercent) 

The IColor parameter will be used to fill the bulb and stem of the thermometer. 
The IBackColor parameter will be used to fill portions of the stem when IPercent is 
less than 100 percent. Finally, IPercent defines the amount of the stem that is filled 
with IColor. It may range from 0 to 100. 

The actual drawing of the fill percentage is done in the DrawTemperature function. 

It takes a similar set of parameters as the DrawThermometer function: 

DrawTemperature (hPS,pRectl,IColor,IBackColor,IPercent) 

This function will be called from the DrawThermometer function after the outline 
and bulb are drawn. It will use the GpiBox function to paint first the unfilled percent at 
the top with IBackColor. The unfilled portion is drawn first because the 100 percent fill 
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point within the rectangle will always be 5 percent from the top. The top of the bulb is 
dependent on its ending arc points. The filled percentage of the stem is then drawn by 
using IColor. In the sample program, the thermometer is drawn in the client area by 
default (see Figure 6.4). A timer may be started or stopped by selecting the Timer menu 
option under Thermometer. The timer causes the fill percentage of the thermometer to 
vary slowly from 0 to 100 percent. 


Figure 6.4. 

GPI Draw thermometer. 



Areas and Paths 

PM provides two types of graphics objects comprised of a collection of drawing primi¬ 
tives: areas and paths. The primitives in an area define one or more closed figures that 
will be filled or filled and outlined by using the current area bundle and line bundle at¬ 
tributes, respectively. The primitives in a path, on the other hand, define a single area to 
be filled, outlined, or stroked. A stroked path results in a wide line. Both areas and paths 
have functions that mark their beginning and end. A completed area or path is referred 
to as a bracket. Before a figure in an area or path can be filled, it must be closed. If the 
primitives in an area bracket do not define a closed figure, an auto closure line is added 
by drawing a straight line from the last point to the first point of the figure. The closed 
figure is then filled based on the construction method for that bracket. 

The fill method for an area or path may be alternate or winding. What these terms 
mean is made more clear by definitions that follow. Alternate fill is determined by the 
number of boundary lines that must be crossed by a line parallel to the X-axis from any 
given point in the figure to a point outside the figure. If an odd number of lines is crossed, 
the point at which the line originated is filled; otherwise, it is left unfilled. The direction 
the boundary lines are drawn does not affect the calculation. Figure 6.5 depicts alternate 
fill mode used when drawing several polygons. 
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Figure 6.5. 
Alternate fill mode. 




The winding fill method uses the direction that boundary lines were drawn to deter¬ 
mine if a point in the figure should be filled. Like alternate fill mode, an imaginary line 
is drawn from a point in the figure parallel to the X-axis to a point outside the figure. 
Rather than counting the number of boundary lines crossed, however, the direction of 
the crossed lines are tracked using a count. Starting with zero, for each line in a given 
direction, one is added to the count. When a boundary line drawn in the opposite direc¬ 
tion is crossed, one is subtracted from the count. If the count is zero when the imaginary 
line exits, the closed figure at that point is not filled; otherwise, that point is filled. Fig¬ 
ure 6.6 depicts winding fill mode used when drawing several polygons. 

Figure 6.6. 

Winding fill mode. 


Areas 

An area is started by calling the GpiBeginArea function. This function takes a PS and 
area fill options as its only parameters. The fill flags specify whether primitives drawn in 
the path should be outlined and whether alternate or winding fill mode should be used. 
The area flags are as follows: 

BA_BOUNDARY Draw boundary lines using the current linebundle 

attributes. This is the default. 

OR: 

BA_NOBOUNDARY Do not draw boundary lines. 

AND: 

BA_ALTERNATE Use alternate fill mode. This is the default. 
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OR: 

BA_WINDING Use winding fill mode. 

The area bundle fill attributes set prior to the call to GpiBeginArea will be used to 
fill the one or more primitives that may be drawn in an area. These are sometimes re¬ 
ferred to as the current attributes. You may set any valid combination of foreground and 
background colors and mix modes, pattern symbols, or fill patterns. The fill attributes 
may be changed within an area bracket; however, those changes will not affect the fill of 
objects in the current bracket. You can think of the current area fill attributes as a snap¬ 
shot of the area bundle when GpiBeginArea was called. Area brackets are the only place 
where the term “current attributes” does not refer to the attributes last set. The line bundle 
attributes may also be changed within an area bracket; however, those changed will affect 
the next primitive drawn if the BA_BOUNDRY flag (or the default) has been used. As is true 
outside a path, only cosmetic boundary lines are drawn. You will recall that the geomet¬ 
ric or wide lines are the result of a stroked path. After all figures are drawn, the area is 
completed by calling the GpiEndArea function. Before the GpiEndArea function returns, 
the figures are drawn in the target PS, and the area is destroyed. In the sample applica¬ 
tion, four stars are drawn in the client area when GpiBegin/EndArea menu item is 
selected. All four combinations of outline and fill methods are demonstrated. 


Paths 

A path may also be used to outline, fill, or stroke a figure with the current attributes. A 
completed path, however, may also be converted into a clipping boundary. The primitives 
within a path bracket define a single figure rather than the multiple figures drawn in an area. 
Apath is started with the GpiBeginPath function and is initially empty. The GpiBeginPath 
function takes two parameters, a PS handle and a path identifier that must be 1. 

A path bracket may not be started within an area bracket, nor may an area bracket 
begin within a path. As primitives are drawn in the path, points defining the figure are 
accumulated. If the starting and ending points in a path are not the same, the path is an 
open figure. Unlike an area, an auto closure line is not generated when a path is closed. 
You may still auto close the figure by using the GpiCloseFigure function. It will add 
points to the path that defines a line from the current position to the starting point. The 
GpiCloseFigure function must be called within a path bracket. In OS/2 2.0, an out¬ 
lined or filled path is limited to 1450 points; Version 2.1 lifts this restriction. The 
GpiEndPath function ends a path bracket. Unlike an area, the path is not rendered by 
the GpiEndPath function. 

Although most GPI functions may be used in a path, there are some restrictions. The 
GpiBox and GpiFullArc functions can be used only with the DR0_0UTLINE option. 
Because each of these already defines a closed figure, if either is used, it may be the only 
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function within a path bracket. Paths are the only method of creating nonrectangular 
clipping regions. The GpiFullArc function may be used to define an ellipse within a 
path that may then be converted to a clipping region. The GpiBox function, however, 
should generally be avoided within a path because filling a rectangle or defining a rectan¬ 
gular region can be accomplished more efficiently by other functions. For example, a 
rectangle defined by GpiBox may be filled by using the DR0_FILL option and a clipping 
region may be created with the GpiCreateRegion function. You also may not begin an 
area within a path or use image primitives such as GpiBitBlt. A complete list of func¬ 
tions valid in a path bracket is shown later in this chapter. 

Unlike an area, closing a path does not render the image and destroy the path. You 
may recall that the interior of figures in an area are always filled. A path gives you much 
greater control of the rendering of the figure. When closed with the GpiEndPath func¬ 
tion, a path may be outlined, filled, stroked, modified, set as a clipping region, or con¬ 
verted to a region. 


Operation 

Fill path interior 
Draw path boundary 
Draw wide boundary lines 
Modify the path 
Set PS clip path 
Convert path to a region 


GP1function 

GpiFillPath 

GpiOutlinePath 

GpiStrokePath 

GpiModifyPath 

GpiSetClipPath 

GpiPathT oRegon 


The sample application will define a path using two splines that define a football¬ 
shaped figure scaled to the client window size. When closed, the path will be filled, out¬ 
lined, or stroked based on the selected menu option. The path is created as follows: 

GpiBeginPath (hPS,1); 

GpiMove (hPS,ptlSpline); 

GpiPolySpline(hPS,3,&ptlSpline[1]); 

GpiPolySpline(hPS,3 3 &ptlSpline[4]); 

GpiEndPath (hPS); 


Because path operations are varied, the fill method is not passed as a parameter to the 
GpiBeginPath function. If a path is to be filled, the desired method (alternate or wind¬ 
ing) is passed to the GpiFillPath function. The GpiFillPath function will fill the in¬ 
terior of the figure by using the current area fill attributes. Current fill attributes for paths 
differ from the current attributes used for area fills: they are truly current. The attributes 
set when the GpiFillPath function is called will be used to fill the path. They may be 
changed before, during, and after a path bracket. If the figure is not closed, an auto clo¬ 
sure line is added to the figure by the GpiFillPath function. Alternate or winding fill is 
determined by the same method as used in area brackets. After the figure is rendered, the 
path is destroyed before returning from GpiFillPath. 
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Boundary lines of a path may also be outlined by using the GpiOutlinePath func¬ 
tion. The function takes a PS handle, a path identifier that must be 1, and a reserved 
option that must be 0. The outline of the path is drawn with the current cosmetic line 
bundle attributes. Unlike a filled path, an open figure is not auto closed. After the figure 
is outlined, the path is destroyed before returning from GpiOutlinePath. 

A wide geometric line can be drawn on the boundries of a figure defined in a path by 
one of two methods. The path may be stroked or modified and filled. A path is stroked 
by using the GpiStrokePath function. This function will convert the current path points 
to points that follow the original boundary based on the geometric line parameters. These 
line parameters define the stroked line width, end, and joins styles. Geometric line width 
specifies the total line width, not the width on either side of the orignal boundary line. 
Line end styles define the appearance of the start and end points in a path. The first point 
drawn in the path is considered the starting point, and the last point drawn by the last 
primitive is the ending point. When multiple primitives are drawn in a path, join style 
determines the appearance of points that shared starting and ending points. The OS/2 
2.1 path limit of 1,450 points applies to both a simple and stroked path. A stroked path 
will have many more points than the simple path it is based on. Although there is no 
formula, limiting a path to be stroked to 500 points is a good guideline. OS/2 2.1 
removes the point limit. Figure 6.7 depicts an outlined and stroked path. 

Figure 6 .7. 

Outlined and 
stroked paths. 

/ 

/ 

/_ . 

Original Path Original and Stroked Path 

Three line end styles are defined: flat, square, and round (see Figure 6.8). Flat end 
style fills the geometric line inclusive of the end point, but not beyond. The end is drawn 
by a line that is perpendicular to the line direction. Flat end style is the default. Square 
line end style is also perpendicular to the current line direction; however, it fills one half 
the geometric line width beyond the end point of the orignal boundary line. The round 
end style also extends past the end point. It will draw as a circle whose center point is the 
original end point and whose radius is one half the geometric line width. In the sample 
application, the effect of changing line end styles can be seen when they are changed as a 
path is being stroked or converted and filled. 
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Figure 6.8. 
Line 

end styles. 



LINETYPE_SQUARE LINETYPE_ROUND 


Three line join styles are also defined: beveled, mitered, and round (see Figure 6.9). 
They all define the appearance of connected figures. Before the join style is applied, each 
line segment can be thought of as having an end style of flat. In the sample application, 
the effect of changing line join styles may be seen when they are changed as a path is 
being stroked or converted and filled. 


Figure 6.9. 
Line join styles. 


LINJOIN_BEVEL 


LINEJOIN_MITRE 


LINEJOIN.ROUND 


A wide line can also be drawn by converting the path to a stroked path with the 
GpiMoclif yPath function. The GpiModif yPath function takes a PS handle, a path iden¬ 
tifier that must be one, and a flag that defines the requested modification. Currently, one 
modification flag is defined. A path can be converted to a stroked path only by using the 
MPATH_STROKE flag. The current geometric line settings are used when converting the 
path. When converted, the path may be filled with the GpiFillPath function by using 
alternate or winding fill mode. 

Regardless of its construction method, the wide line will be filled with the current 
area bundle fill attributes. The line color and style have no effect on the figure. The sample 
program will actually fill the wide line with a vertical pattern. 

A path or modified path may also be set as a clipping area in the PS by using the 
GpiSetClipPath function. This function can reset the clipping path or define a new one 
that is the intersection of the current and new clip paths. After the GpiSetClipPath func¬ 
tion is called, the path is no longer valid. As for a filled path, the clip path may be either 
alternate or winding. If the figure is not closed, an auto closure line is added to the figure 
before being set as the clip path. By using the GpiModif yPath, you can set a clip path 
that is the same as that defined by a stroked path. In the sample application, you may set 
the path or the stroked path of the football as the current clip path. When these options 
are selected, the screen is filled with a tiled bitmap image after the clip path has been set. 


277 





Real-Worid Programming for 


OS/2 2.1 


Resources 

Resources are definitions of objects such as pointers, strings, and icons that are compiled 
by the resource compiler and bound to an executable or DLL. When a resource is loaded 
by a function such as WinLoadPointer, the process loading it becomes the owner. Threads 
created by this process will have access to those resources. 

Resources that are created or loaded as part of one process may not be shared with 
another process. Initially, this may not seem like a large restriction; however, it should be 
considered when designing your application. For example, imagine that your applica¬ 
tion is comprised of a single executable and a DLL. If resources are loaded in the DLL 
and accessed by the executable, some conflicts could arise. Suppose your DLL loads and 
manages a group of cursors that the application can reference by index. If the DLL loads 
only one copy of the resources, the first instance of your application—process one—will 
have access to those pointer resources. If a second instance of your application is started— 
process 2—it will not have access to the loaded cursor resources because process 1 is the owner. 

For this to work, the DLL would need to load the cursor resources and maintain the 
handles for each process. 

Presentation Space Attribute Defaults 

The PS attribute defaults discussed previously in this chapter are listed below in 
Table 6.1. 

Table 6.1. Default Presentation Space Attributes 

Attribute Default Value _ Functions to Query /Modify 

Foreground Color Display- GpiSet/QueryAttrs 

SYSCLR_WINDOWTEXT - ABB_COLOR 

Printer - Contrast to paper - ab.lColor 

GpiSet/QueryColor 

Background Color Display - SYSCLR_WINDOW^ GpiSet/QueryAttrs 

Printer - Paper color - ABB_BACK_COLOR 

- ab.lBackColor 
GpiSet/QueryBackColor 

Forground Mix Mode FM_OVERPAINT GpiSet/QueryAttrs 

- ABB_MIX_MODE 

- ab.usMixMode 
GpiSet/QueryMix 
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Attribute Default Value Functions to Query /Modify 


Background Mix 

Mode 

BM_LEAVEALONE 

GpiSet/QueryAttrs 
-ABB_BACK_MIX_MODE 
- ab.usBackMixMode 
GpiSet/QueryBackMix 

Pattern Set 

LCID_DEFAULT 

GpiSet/QueryAttrs 

- ABB_SET 

- ab.usSet 

GpiSet/QueryPatternSet 

Pattern Symbol 

PATSYM_SOLID 

GpiSet/QueryAttrs 

- ABB_SYMBOL 

- ab.usSymbol 

GpiSet/QueryPattern 

Pattern Reference 

(0,0) 

GpiSet/QueryAttrs 

- ABB_REF_POINT 

- ab.ptlRefPoint 

GpiSet/ 

QueryPatternRefPoint 

CHAR 



Foreground Color 

Display - 

SYSCLR_WINDOWTEXT 
Printer - Contrast to paper 

GpiSet/QueryAttrs 

- CBB_COLOR 

- cb.lColor 

GpiSet/QueryColor 

Background Color 

Display - SYSCLR_WINDOW 
Printer - Paper color 

GpiSet/QueryAttrs 

- CBBJBACK_COLOR 

- cb.lBackColor 

GpiSet/QueryBackColor 

Foreground Mix Mode 

FM_OVERPAINT 

GpiSet/QueryAttrs 

- CBB_MIX_MODE 

- cb.usMixMode 

GpiSet/QueryMix 

Background Mix Mode BM_LEAVEALONE 

GpiSet/QueryAttrs 

- CBB_BACK_MlX_MODE 

- cb.usBackMixMode 

GpiSet/QueryBackMix 


continues 
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Table 6.1. continued 



Attribute 

Default Value 

Functions to Query /Modify 

Character Angle 

(1,0) 

GpiSet / QueryAttrs 

- CBB_ANGLE 

- cb.ptlAngle 

GpiSet/QueryCharAngle 

Character Shear 

(0,1) 

GpiSet/QueryAttrs 

- CBB_SHEAR 

- cb.ptlShear 

GpiSet/QueryCharShear 

Character Direction 

Left to Right 

GpiSet/QueryAttrs 

- CBB_DIRECTION 

- cb.usDirection 

GpiSet/QueryCharDirection 

Character Mode 

CH_MODEl 

GpiSet/QueryAttrs 

- CBB_MODE 

- cb.usPrecision 

GpiSet/QueryCharMode 

Extra Spacing All 
Characers 

zero 

GpiSet/QueryAttrs 

- CBB_ 

- cb.fxExtra 

GpiSet/QueryCharExtra 

Extra Spacing Break 
Character Only 

zero 

GpiSet/QueryAttrs 

- CBB_ 

- cb.fxBreakExtra 

GpiSet/ 

Query CharB reakExtr a 

IMAGEBUNDLE 

Foreground Color 

Display - 

SYSCLR_WINDOWTEXT 
Printer - Contrast to paper 

GpiSet/QueryAttrs 

- IBB_COLOR 

- Ib.lColor 

GpiSet/QueryColor 

Background Color 

Display - SYSCLR_WINDOW 
Printer - Paper color 

GpiSet/QueryAttrs 

- ibb_back_color 

- ib.lBackColor 

GpiSet/QueryBackColor 
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Attribute 

Default Value 

Functions to Query /Modify 

Foreground Mix Mode 

FM_OVERPAINT 

GpiSet/QueryAttrs 

- IBB_MIX_MODE 

- ib.usMixMode 

GpiSet/QueryMix 

Background Mix 

Mode 

BM_LEAVEALONE 

GpiSet/QueryAttrs 

- IBB_BACK_MIX_MODE 

- ib.usBackMixMode 

GpiSet/QueryBackMix 

LINEBUNDLE 

Foreground Color 

Display - 

SYSCLR_WINDOWTEXT 
Printer - Contrast to paper 

GpiSet/QueryAttrs 

- LBB_COLOR 

- lb.lColor 

GpiSet/QueryColor 

Background Color 

Display - SYSCLR_WINDOW 
Printer - Paper color 

GpiSet/QueryAttrs 

- lbbjback_color 

- Ib.lBackColor 

GpiSet/QueryBackColor 

Foreground Mix Mode 

FMJDVERPAINT 

GpiSet/QueryAttrs 

- LBB_MIX_MODE 

- Ib.usMixMode 

GpiSet/QueryMix 

Background Mix Mode BM_LEAVEALONE 

GpiSet/QueryAttrs 

- LBB_BACK_MIX_MODE 

- lb.usBackMixMode 

GpiSet/QueryBackMix 

Cosmetic Width 

(1,0) 

GpiSet/QueryAttrs 

- LBB_WIDTH 

- lb.fxWidth 

GpiSet/QueryLineWidth 

Geometric Width 

1 

GpiSet/QueryAttrs 

- LBB_GEOM_WIDTH 

- ib.lGeomWidth 

GpiSet/ 

QueryLineWidthGeom 



continues 
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Table 6.1. continued 


Attribute 

Default Value 

Functions to Query lModify 

Line Type 

LINETYPE_SOLID 

GpiSet / QueryAttrs 

- LBB_TYPE 

- lb.ulType 

GpiSet/QueryLineType 

Geometric End Style 

LINEEND_FLAT 

GpiSet/QueryAttrs 

- LBB_END 

- lb.ulEnd 

GpiSet/QueryLineEnd 

Geometric Join Style 

LINEJOIN_BEVEL 

GpiSet/QueryAttrs 

- LBB JOIN 

- lb.uljoin 

GpiSet/Query Linejoin 

MARKERBUNDLE 

Foreground Color 

Display - 

SYSCLR_WINDOWTEXT 
Printer - Contrast to paper 

GpiSet/QueryAttrs 

- MBB__COLOR 

- mb.lColor 

GpiSet/QueryColor 

Background Color 

Display - SYSCLR_WINDOW 
Printer - Paper color 

GpiSet/QueryAttrs 

- MBB_BACK_COLOR 

- mb.lBackColor 

GpiSet/QueryBackColor 

Foreground Mix Mode 

FM_OVERPAINT 

GpiSet/QueryAttrs 

- MBB_MIX_MODE 

- mb.usMixMode 

GpiSet/QueryMix 

Background Mix Mode 

BM_LEAVEALONE 

GpiSet/QueryAttrs 

- MBB_BACK_MIX_MODE 

- mb.usBackMixMode 
GpiSet/QueryBackMix 

Marker Set 

LCID_DEFAULT 

GpiSet/QueryAttrs 

- MBB_SET 

- mb.usSet 

GpiSet/QueryMarkerSet 
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Attribute 

Default Value 

Functions to Query /Modify 

Marker Symbol 

MARKSYM_CROSS 

GpiSet/QueryAttrs 

- MBB_SYMBOL 

- mb.usSymbol 

GpiSet/QueryMarker 

Marker Box 

(CAPS_MARKER_WIDTH, 

CAPSJvLARKERJHEIGHT) 

GpiSet/QueryAttrs 

- MBB_BOX 

- mb.sizfxCell 

GpiSet/QueryMarker Box 

Current position 

(0,0) 

GpiSet/ 

QueryCurrentPosition 

GpiMove 

Color table 

Indexed 

GpiCreate/ 

QueryLogColorT able 
GpiRealizeColorT able 


Functions That Can Be Called 
in a Path Bracket 


Function 

Restriction 

GpiBeginElement 

GpiBox 

DRO_OUTLINE draw option only. 

GpiCallSegmentMatrix 

GpiCharString 

Current font must be outline. 

GpiCharStringAt 

Current font must be outline. 

GpiCharStringPos 

Current font must be outline. 

GpiCharStringPosAt 

Current font must be outline. 

GpiCloseFigure 

GpiComment 

GpiCreateLogFont 

Only outline fonts may be 

GpiDeleteSetld 

GpiElement 

GpiEndElement 

GpiEndPath 

GpiFullArc 

rendered. 

DRO_OUTLINE draw option only. 

GpiLabel 
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GpiLine 

GpiMarker 

GpiMove 

GpiOfFsetElementPointer 

GpiPartialArc 

GpiPointArc 

GpiPolyFillet 

GpiPolyFilletSharp 

GpiPolyLine 

GpiPolyMarker 

GpiPolySpline 

GpiPop 

GpiPutData 

G p i QueryAr cP arams 

GpiQueryAttrMode 

GpiQueryCurrentPosition 

GpiSetArcP arams 

GpiSetAttrMode 

GpiSetAttrs 

GpiSetCharAngle 

GpiSetCharBox 

GpiSetCharDirection 

GpiSetCharMode 

GpiSetCharSet 

GpiSetCharShear 

GpiSetColor 

GpiSetCp 

GpiSetCurrentPosition 

GpiSetEditMode 

GpiSetLineEnd 

GpiSetLineJoin 

GpiSetLineType 

GpiSetLineWidth 

GpiSetMarker 

GpiSetMarkerBox 

GpiSetMarkerSet 

GpiSetMix 

GpiSetModelT ransformMatrix 
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The Drawing Sample Application 

The following files are needed to create the PMDRAW sample application: 

ABOUT.DLG 

DRAW.C 

DRAW.DEF 

DRAW.H 

DRAW.ICO 

DRAW.RC 

STAR.BMP 

STAR.DRW 

THERMO.C 

THERMO.H 


DRAW.H 


/* 


GPI Drawing Header File 
Chapter 6 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define ID_APPNAME 1 
#define IDS_APPNAME 1 
#define IDS_TIMERON 2 
#define IDS_TIMEROFF 3 
#define IDS_NOB_WIND 4 
#define IDS_BOUND_WIND 5 
#define IDS_NOB_ALT 6 
#define IDS_BOUND_ALT 7 

#define ID_STAR 50 

#define IDM_DRAW 100 
#define IDM_THERM 101 
#define IDM_TIMER 102 
#define IDM_ABOUT 103 
#define IDM_AREAS 200 
#define IDM_AREA_STARS 201 
#define IDM_POLY_STARS 202 
#define IDM_PATHS 300 
#define IDM_FILL_PATH 301 
#define IDM_OUTLINE_PATH 302 


#define IDM_CONVERT_ALT_PATH 303 
#define IDM_CONVERT_WIND PATH 304 
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#define IDM_STROKE_PATH 305 
#define IDM_CLIP_PATH 306 
#define IDM_CLIP_STROKE_PATH 307 
#define IDM_BEVEL 308 
#define IDM_ROUND 309 
#define IDM_MITRE 310 
#define IDM_FLAT_END 311 
#define IDM_ROUND_END 312 
#define IDM SQUARE_END 313 


#define MAX_STRING 80 

void APIENTRY calculate_points(MPARAM); 

void APIENTRY process_command (HWND,MPARAM, MPARAM); 

void APIENTRY process_paint(HWND); 


DRAW.C 


/* 


GPI Drawing Program 
Chapter 6 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL__WIN 
#define INCL_GPI 
#define INCL_GPIPOLYGON 
#include <os2.h> 

#include "draw.h" 

#include "thermo.h" 

#include "..\common\about.h" 

extern LONG APIENTRY GpiPolygons(HPS,ULONG,PPOLYGON,ULONG,ULONG); 

#ifdef POLYGON_EXCL 
#undef POLYGON_EXCL 
#endif 

#define P0LYG0N_EXCL 1 

MRESULT EXPENTRY ClientWndProc (HWND,UL0NG,MPARAM,MPARAM); 


HAB hab; 

HWND hWndFrame, 

hWndClient; 
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HWND hMenu; 

CHAR szTitle[64]; 

CHAR szFontFace[] = " 8 .Helv"; 

USHORT usMode = IDM_THERM; 

USHORT usLineJoin = IDM_BEVEL; 

USHORT usLineEnd = IDM_FLAT_END; 

PVOID pMem; 

RECTL ThermRectl; 
int iPercent = 0 ; 

BOOL bTimer = FALSE; 

BOOL bRising = TRUE; 

POINTL ptlStar [5][5] ; 

POINTL ptlSpline [7]; 

USHORT usJoinStyles [] = 

{LINEJOIN_BEVEL, LINEJOIN_ROUND, LINEJOIN_MITRE}; 

USHORT usEndStyles [] = 

{LINEEND_FLAT, LINEEND_ROUND, LINEEND_SQUARE}; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG fIFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | 

FCF_SIZEBORDER j FCF_MINMAX | 
FCF_SHELLPOSITION ! FCF_TASKLIST | 

FCF_ICON J FCF_MENU; 

CHAR szClientClass[] = "CLIENT"; 
int iClientHeight; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab,szClientClass,ClientWndProc, CS_SIZEREDRAW,0); 
WinLoadString (hab,0,IDS_APPNAME,sizeof(szTitle),szTitle); 

DosAllocMem( (PPVOID)&pMem,0x1 000 ,PAG_READ j PAGJ/VRITE) ; 

DosSubSet(pMem,DOSSUB_INIT | DOSSUB_SPARSE_OBJ,8192); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0 , 

&fIFrameFlags,szClientClass, szTitle,0,0,ID_APPNAME,&hWndClient); 

iClientHeight = WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - 
WinQuerySysValue(HWND_DESKTOP,SV_CYICON); 
WinSetWindowPos (hWndFrame,HWND_TOP,0, 

WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - iClientHeight 
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WinQuerySysValue(HWNDJ5ESKT0P,SV_CXSCREEN),iClientHeight, 
SWP_SHOW | SWP_ACTIVATE 1 SWP_ZORDER | SWP_SIZE | SWP_MOVE); 

hMenu = WinWindowFromID (hWndFrame,FID_MENU); 


while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 
WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 
WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 

DosFreeMem(pMem); 
return (0); 

} 


void APIENTRY calculate_points(MPARAM INewSize) 


This function will update the point arrays for the stars and 
splines when the window is resized. 


int i,j; 

int X,Y; 

int iWidth,iHeight; 

POINTL ptl[5]; 

/* Calculate the location of the 4 stars */ 
iWidth = SHORT1FROMMP(INewSize); 
iHeight = SH0RT2FR0MMP(INewSize); 

X = (iWidth / 3) - 1; 

Y = (iHeight / 2) - 1; 
ptl[0].x = -(X / 3); 
ptl[0].y = -(Y / 2); 
ptl[1],x = X / 2; 
ptl[1].y = Y / 6; 
pt1[2].x = -(X / 2); 
ptl[2].y = Y / 6; 
pt1[3].x = -ptl[0].x; 
pt1[3].y = ptl[0].y; 
ptl[4].x = 0; 
pt1[4].y = Y / 2; 

for (i = 0;i <= 4;i++) 

{ 

if ((i == 0) !| (i == 2)) 

X = iWidth / 4; 
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else 

X = iWidth - (iWidth / 4); 
if ((i == 2) II (i == 3)) 

Y = iHeight / 4; 
else 

Y = iHeight - (iHeight / 4); 

for (j = 0;j <= 4;j++) 

{ 

ptlStar[i][j].x = X + ptl[j].x; 
ptlStar[i][j].y = Y + ptl[j].y; 

} 

} 


/* Calculate 
ptlSpline[0].x 
ptlSpline[0].y 
ptlSpline[1 ] .x 
ptlSpline[1].y 
ptlSpline[2].x 
ptlSpline[2].y 
ptlSpline[3].x 
ptlSpline[3].y 
ptlSpline[4].x 
ptlSpline[4].y 
ptlSpline[5].x 
ptlSpline[5].y 
ptlSpline[6].x 
ptlSpline[6].y 


the points for the spline */ 
iWidth / 4; 
iHeight / 2; 
iWidth *3/8; 
iHeight *3/4; 
iWidth - ptlSpline[1].x; 
ptlSplinefl].y; 
iWidth - ptlSpline[0].x; 
ptlSpline[0].y; 
ptlSpline[2].x; 
iHeight / 4; 
ptlSpline[1].x; 
ptlSpline[4].y; 
ptlSpline[0].x; 
ptlSpline[0].y; 


void APIENTRY process_command(HWND hWnd,MPARAM mpl,MPARAM mp2) 

/*...-.*\ 


All WM_COMMAND messages received by the client window will be 
processed here. 



char szTemp [MAX_STRING]; 


switch(SH0RT1FROMMP(mpl)) 

{ 

case IDM_THERM: 

WinSendMsg (hMenu,MM_SETITEMATTR,MPFR0M2SH0RT(usMode,TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 

WinSendMsg (hMenu,MM_SETITEMATTR 3 MPFR0M2SH0RT(IDM_THERM,TRUE), 
MPFROM2SHORT(MIA_CHECKED 5 MIA_CHECKED)); 
usMode = SH0RT1FROMMP(mpl); 
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WinlnvalidateRect(hWndClient,0 3 FALSE); 
break; 

case IDM_TIMER: 

if (usMode != IDM_THERM) 
break; 
if (bTimer) 

{ 

WinStopTimer(hab 3 hWnd 3 1); 
bTimer = FALSE; 

WinLoadString (hab 3 0 3 IDS_TIMERON,MAX_STRING,(PSZ)szTemp); 
WinSendMsg (hMenu , MM_SETITEMTEXT 3 MPFROMSHORT(IDM_TIMER) 3 
(MPARAM)szTemp); 

} 

else 

{ 

WinStartTimer (hab,hWnd 3 1 3 0); 
bTimer = TRUE; 

WinLoadString (hab,0,IDS_TIMEROFF 3 MAX_STRING 3 (PSZ)szTemp); 
WinSendMsg (hMenu 3 MM_SETITEMTEXT,MPFROMSHORT(IDM_TIMER) 3 
(MPARAM)szTemp); 

} 

break; 

case IDM_AREA_STARS: 
case IDM_POLY_STARS: 
case IDM_FILL_PATH: 
case IDM_OUTLINE_PATH: 
case IDM_CONVERT_ALT_PATH: 
case IDM_CONVERT_WIND_PATH: 
case IDM_STROKE_PATH: 
case IDM_CLIP_PATH: 
case IDM_CLIP_STROKE_PATH: 
if (bTimer) 

WinSendMsg(hWnd 3 WM_COMMAND 3 MPFROMSHORT(IDM_TIMER),0); 
WinSendMsg (hMenu 3 MM_SETITEMATTR 3 MPFROM2SHORT(usMode,TRUE) 3 
MPFR0M2SH0RT(MIA_CHECKED , FALSE)); 
usMode = SHORT1FROMMP(mpl); 

WinSendMsg (hMenu 3 MM_SETITEMATTR 3 MPFROM2SHORT(usMode , TRUE) 3 
MPFR0M2SH0RT(MIA_CHECKED 3 MIA_CHECKED)); 

WinlnvalidateRect(hWndClient 3 0,FALSE); 
break; 

case IDM_BEVEL: 
case IDM_R0UND: 
case IDM_MITRE: 

WinSendMsg (hMenu 5 MM_SETITEMATTR,MPFR0M2SH0RT(usLineJoin,TRUE) 
MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 
usLineJoin = SH0RT1FROMMP(mpl); 

WinSendMsg (hMenu 3 MM_SETITEMATTR,MPFR0M2SH0RT(usLineJoin 3 TRUE) 
MPFR0M2SH0RT(MIA_CHECKED , MIA_CHECKED)); 

WinlnvalidateRect(hWndClient 3 0 3 FALSE); 
break; 

case IDM FLAT END: 
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case IDM_ROUND_END: 
case IDM_SQUARE_END: 

WinSendMsg (hMenu,MM_SETITEMATTR,MPFR0M2SH0RT(usLineEnd,TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 
usLineEnd = SHORT1FROMMP(mpl); 

WinSendMsg (hMenu,MM_SETITEMATTR,MPFR0M2SH0RT(usLineEnd , TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 

WinlnvalidateRect(hWndClient,0,FALSE); 
break; 

case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

mp2; 

} 


void APIENTRY process_paint(HWND hWnd) 

/*.*\ 


This function will paint the client area based on the current 
display mode. The following modes are supported: 


IDM_THERM 

IDM_AREA_STARS 

IDM_POLY_STARS 

IDM_FILL_PATH 

IDM_0UT LIN E_PATH 

IDM_CONVERT_ALT_PATH 

IDM_CONVERT_WIND_PATH 

IDM_STROKE_PATH 

IDM_CLIP_STROKE_PATH 

IDM CLIP PATH 


Draw a thermometer with the current fill 
percentage. 

Draw 4 stars with all combinations of fill 
and outline using areas. 

Draw 4 stars with all combinations of fill 
and outline using the polygon primitive. 

Fill a football shaped path created with 2 
spines. 

Outline a football shaped path created with 
2 spines. 

Modifies a path and then fills it with 
alternate fill mode. 

Modifies a path and then fills it with 
winding fill mode. 

Draw a football shaped wide line using 2 
spines. 

Converts a path and then select it as the 
clipping region. 

Select the path created with 2 splines as a 
clipping region and fill the client area with 
bitmaps. 


\*.*/ 

{ 

HPS hPS; 

BOOL bAreas = FALSE; 

RECTL Recti; 

POLYGON poly; 
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LINEBUNDLE 

AREABUNDLE 

HBITMAP 

PSZ 

int 


lb; 

ab; 

hBitmap; 

pLabel; 

iRows, iColumns; 


int i,j; 

BITMAPINFOHEADER bi; 
POINTL ptl; 


WinSetPresParam(hWnd 3 PP_FONTNAMESIZE,strlen(szFontFace)+1, 
(PVOID)szFontFace); 
hPS = WinBeginPaint(hWnd 3 0,&Rectl); 

WinFillRect(hPS,(PRECTL)&Rectl,CLR_PALEGRAY); 
ab.lColor = CLR_BLUE; 

switch (usMode) 

{ 

case IDM_THERM: 

DrawThermometer(hPS,(PRECTL)&ThermRectl 3 0 3 CLR_RED 3 
CLR_PALEGRAY,iPercent); 
break; 

case IDM_AREA_STARS: 
bAreas = TRUE; 
ab.lColor = CLR_RED; 
case IDM_POLY_STARS: 

DosSubAlloc(pMem,(PPVOID)&pLabel 3 MAX_STRING); 

GpiSetAttrs (hPS,PRIM_AREA 3 ABB_COLOR 3 0,&ab); 
poly.ulPoints = 5; 

GpiSetCurrentPosition (hPS,&ptlStar[0][0]); 
if (bAreas) 

{ 

GpiBeginArea (hPS 3 BA_NOBOUNDARY | BA_WINDING); 
GpiPolyLine (hPS 3 5L 3 &ptlStar[0][0]); 

GpiEndArea (hPS); 

} 

else 

{ 

poly.aPointl = &ptlStar[0][0]; 

GpiPolygons (hPS,1L 3 &poly 3 BA_NOBOUNDARY \ BA_WINDING 3 
POLYGON_EXCL); 

} 

i = WinLoadString (hab 3 0,IDS_NOB_WIND 3 MAX_STRING 3 pLabel); 
GpiCharStringAt (hPS 3 &ptlStar[0][2] 3 i 3 pLabel); 

GpiSetCurrentPosition (hPS,&ptlStar[1][0]); 
if (bAreas) 

{ 

GpiBeginArea (hPS,BA_BOUNDARY | BA_WINDING); 



Chapter O Presentation Spaces and Drawing 


GpiPolyLine (hPS,5L,&ptlStar[1][0]); 

GpiEndArea (hPS); 

} 

else 

{ 

poly.aPointl = &ptlStar[1][0]; 

GpiPolygons (hPS,1L,&poly,BA_B0UNDARY j BAJVINDING, 
POLYGON_EXCL); 

} 

i = WinLoadString (hab,0,IDS_BOUND_WIND,MAX_STRING,pLabel) 
GpiCharStringAt (hPS,&ptlStar[1][2],i,pLabel); 

GpiSetCurrentPosition (hPS,&ptlStar[2][0]); 
if (bAreas) 

{ 

GpiBeginArea (hPS,BA_NOBOUNDARY J BA_ALTERNATE); 
GpiPolyLine (hPS,5L,&ptlStar[2][0]); 

GpiEndArea (hPS); 

} 

else 

{ 

poly.aPointl = &ptlStar[2][0]; 

GpiPolygons (hPS,1L,&poly,BA_NOBOUNDARY | BA_ALTERNATE, 
POLYGON_EXCL); 

} 

i = WinLoadString (hab,0,IDS_NOB_ALT,MAX_STRING,pLabel); 
GpiCharStringAt (hPS,&ptlStar[2][2],i,pLabel); 

GpiSetCurrentPosition (hPS,&ptlStar[3][0]); 
if (bAreas) 

{ 

GpiBeginArea (hPS,BAJ30UNDARY | BA_ALTERNATE); 
GpiPolyLine (hPS,5L,&ptlStar[3][0]); 

GpiEndArea (hPS); 

} 

else 

{ 

poly.aPointl = &ptlStar[3][0]; 

GpiPolygons (hPS,1L,&poly,BA_BOUNDARY | BA_ALTERNATE, 
POLYGON_EXCL); 

} 

i = WinLoadString (hab,0,IDS_BOUND_ALT,MAX_STRING,pLabel); 
GpiCharStringAt (hPS,&ptlStar[3][2],i,pLabel); 

DosSubFree(pMem,pLabel,MAX_STRIMG); 
break; 

case IDM_FILL_PATH: 
case IDM_OUTLINE_PATH: 

ab.usSymbol = PATSYM_HORIZ; 

ab.lColor = CLR_WHITE; 

ab.lBackColor = CLR_BLUE; 
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ab.usBackMixMode = BM_OVERPAINT; 

GpiSetAttrs (hPS,PRIM_AREA,ABB_C0L0R J ABB_SYMBOL | 
ABB_BACK_C0L0R | ABB_BACK_MIX_MODE,0,&ab); 

GpiBeginPath (hPS,1); 

GpiMove (hPS,ptlSpline); 

GpiPolySpline(hPS,3 5 &ptlSpline[ 1 ]); 
GpiPolySpline(hPS,3,&ptlSpline[4]); 

GpiEndPath (hPS); 

if (usMode == IDM_FILL_PATH) 

GpiFillPath(hPS,1,FPATH_ALTERNATE); 
else 
{ 

lb.lColor = CLR_RED; 

GpiSetAttrs(hPS,PRIM_LINE,ABB_C0L0R,0,&lb); 
GpiOutlinePathfhPS,1,0); 

} 

break; 

case IDM_CONVERT_ALT_PATH: 
case IDM_CONVERT_WIND_PATH: 
case IDM_STROKE_PATH: 

ab.usSymbol = PATSYM_VERT; 

ab.lColor = CLR_BLUE; 

GpiSetAttrs (hPS,PRIM_AREA,ABB_C0L0R j ABB_SYMBOL,0,&ab); 
lb.lGeomWidth = 20; 

lb.usJoin = usJoinStyles[usLineJoin - IDM_BEVEL]; 
lb.usEnd = usEndStyles [usLineEnd - IDM_FLAT_END]; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_GEOM_WIDTH | LBB_JOIN | LBB_END, 
0,&lb); 

GpiBeginPath (hPS,1); 

GpiMove (hPS,ptlSpline); 

GpiPolySpline(hPS,3 3 &ptlSpline[1]); 
GpiPolySpline(hPS,3,&ptlSpline[4]); 

GpiEndPath (hPS); 

if (usMode == IDM_STROKE_PATH) 

GpiStrokePath(hPS 5 1,FPATH_ALTERNATE); 
else 
{ 

GpiModifyPath (hPS,1,MPATH_STROKE); 
if (usMode == IDM_CONVERT_ALT_PATH) 

GpiFillPath(hPS,1,FPATH_ALTERNATE); 
else 

GpiFillPath(hPS,1,FPATHJVINDING); 

} 

break; 

case IDM CLIP_STROKE_PATH: 
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case IDM_CLIP_PATH: 

GpiBeginPath (hPS,1); 

GpiMove (hPS,ptlSpline); 

GpiPolySpline(hPS,3,&ptlSpline[ 1 ]); 

GpiPolySpline(hPS,3,&ptlSpline[4]); 

GpiEndPath (hPS); 

if (usMode == IDM_CLIP_STROKE_PATH) 

{ 

lb.lGeomWidth = 20; 

lb.usJoin = usJoinStyles[usLineJoin - IDM_BEVEL]; 
lb.usEnd = usEndStyles [usLineEnd - IDM_FLAT_END]; 
GpiSetAttrs (hPS,PRIM_LINE,LBB_GEOM_WIDTH | LBB_J0IN j 
LBB_END,0,&lb); 

GpiModifyPath (hPS,1,MPATH_STROKE); 

} 

GpiSetClipPath(hPS,1,FPATH_ALTERNATE | SCP_AND); 
hBitmap = GpiLoadBitmap(hPS,0,ID_STAR,0,0); 

GpiQueryBitmapParameters(hBitmap,(PBITMAPINFOHEADER)&bi); 

iRows = Recti.xRight / bi.cx; 

iColumns = Recti.yTop / bi.cy; 

ptl.x = 0; 

ptl.y = 0; 

for (i = 0;i <= iRows;i++) 

{ 

for (j = 0;j <= iColumns; j++) 

{ 

WinDrawBitmap(hPS,hBitmap,0,&ptl,0,0,DBM_NORMAL); 
ptl.y += bi.cy; 

} 

ptl.y = 0; 
ptl.x += bi.cx; 

} 

break; 

} 

WinEndPaint (hPS); 


void APIENTRY update_thermometer (FIWND hWnd) 


This function will process the timer message for the thermometer 
causing it to redraw cycling through the fill percentages 0 to 100. 


/ 
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HPS hPS; 

hPS = WinGetPS(hWnd); 

DrawTemperature(hPS,(PRECTL)&TherraRectl,CLR_RED,CLR_PALEGRAY, 
iPercent); 

WinReleasePS (hPS); 
if (bRising) 

{ 

iPercent++; 
if (iPercent > 100) 

{ 

bRising = FALSE; 
iPercent- -; 

} 

} 

else 

{ 

iPercent - -; 
if (iPercent < 0) 

{ 

bRising = TRUE; 
iPercent++; 

} 

} 

} 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

/*.*\ 


This is the application callback which handles the messages 
necessary to maintain the client window. 


BOOL bHandled = TRUE; 
MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_CREATE: 

ThermRectl.xLeft = 50; 
ThermRectl.yBottom = 50; 
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ThermRectl.yTop = 350; 

ThermRectl.xRight = 100; 
break; 

case WM_COMMAND: 

process_command(hWnd,mp1 ,mp2); 
break; 

case WM_TIMER: 

update_thermometer(hWnd); 
break; 

case WM_PAINT: 

process_paint(hWnd); 
break; 

case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl),PVOIDFROMMP(mp2),CLR__PALEGRAY); 

mReturn = MRFROMLONG(0L); 

break; 

case WM_SIZE: 

calculate_points(mp2); 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


DRAW.DEF 


NAME 

DESCRIPTION 

PROTMODE 

HEAPSIZE 

STACKSIZE 

IMPORTS 

EXPORTS 


DRAW WINDOWAPI 

'Draw Sample Program (c) Blain, Delimon, & English, 1993' 

4096 

32768 

GpiPolygons = PMGPI.650 
ClientWndProc 
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DRAW.RC 


/* 


Draw Resource File 
Chapter 6 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 
#include "draw.h" 


ICON ID_APPNAME DRAW.ICO 
BITMAP ID STAR STAR.BMP 


RCINCLUDE ..\common\about.dig 


MENU ID_APPNAME 
BEGIN 

SUBMENU "-Thermometer", 

BEGIN 

MENUITEM "Display", 

MENUITEM "Start Timer", 
MENUITEM SEPARATOR 
MENUITEM "About...", 

END 

SUBMENU "-Areas", 

BEGIN 

MENUITEM "GpiBegin/EndArea", 
MENUITEM "GpiPolygons", 


IDM_DRAW 

IDM_THERM, 0, MIA_CHECKED 
IDM_TIMER 

IDM_ABOUT 

IDM_AREAS 

IDM_AREA_STARS 
IDM POLY STARS 


Fill Path", 

Outline Path", 
Convert/Fill Path ALT", 
Convert/Fill Path WIND" 
Stroke Path", 

Clip To Path", 

Clip To Stroke Path", 


IDM_PATHS 

IDM_FILL_PATH 
IDM_0UT LIN E_PATH 
IDM_CONVERT_ALT_PATH 
, IDM_CONVERT_WIND_PATH 
IDM_STROKE_PATH 
IDM_CLIP_PATH 
IDM CLIP STROKE PATH 


END 

SUBMENU "-Paths", 

BEGIN 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM 
MENUITEM SEPARATOR 
MENUITEM "Line Join Bevel", 
MENUITEM "Line Join Round", 
MENUITEM "Line Join Mitre", 
MENUITEM SEPARATOR 
MENUITEM "Line End Flat", 
MENUITEM "Line End Round", 
MENUITEM "Line End Square", 
END 


IDM_BEVEL, 0, MIA_CHECKED 

IDM_R0UND 

IDMJ/IITRE 

IDM_FLAT_END, 0, MIA_CHECKED 

IDM_ROUND_END 

IDM SQUARE END 
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STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 


IDS_APPNAME 

IDS_NOB_WIND 

IDS_BOUND_WIND 

IDS_NOB_ALT 

IDS_BOUND_ALT 

IDS_TIMERON 

IDS TIMEROFF 


"GPI Draw" 

11 BA_N0B0UNDARY 
11 BA_BOUNDARY | 

" BA_N0B0UNDARY 
" BA_BOUNDARY j 
"Start Timer" 
"Stop Timer" 


END 


| BAJVINDING" 
BA_WINDING" 

| BA_ALTERNATE 
BA ALTERNATE" 


THERMO.H 


/* 


Thermometer Header File 
Chapter 6 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define TS_SHOW_PERCENT 0x0001 

BOOL APIENTRY DrawThermometer (HPS,PRECTL,LONG,LONG,LONG,LONG); 
BOOL APIENTRY DrawTemperature (HPS,PRECTL,LONG,LONG,LONG); 


THERMO.C 


/* 


Thermometer Drawing sample 
Chapter 6 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#define INCL_GPI 
#include <os2.h> 
#include "thermo.h 


BOOL APIENTRY DrawTemperature (HPS hPS,PRECTL pRectl,LONG IColor, 

LONG IBackColor,LONG IPercent) 

/*.*\ 


This function will fill draw the vertical bar portion of the 
thermometer. IColor is used to fill IPercent of the bar starting 
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at the top of the bulb. IBackColor is used to fill the remainder 
of the bar. The rectangle identified by pRectl should be identical 
to that supplied to DrawThermometer. 

hPS Presentation space to render in. 

pRectl Bounding box of the thermometer. 

IColor Color index used to fill bulb and stem of thermometer. 
IBackColor Color to fill the remainder of the stem (100 - IPercent). 
IPercent Amount to fill the thermometer. Valid range is 0 to 100. 


\*.-.*/ 

{ 

AREABUNDLE ab; 

RECTL Recti; 

int iWidth = (pRectl->xRight - pRectl->xLeft) / 3; 

int iBoxHeight = pRectl->yTop - pRectl->yBottom; 

int iBarHeight = (iBoxHeight * 70) / 100; 

/* Range check the percent */ 
if (IPercent > 100) 

IPercent = 100; 
else if (IPercent < 0) 

IPercent = 0; 

Recti.xLeft = pRectl->xLeft + iWidth; 

Recti.yTop = pRectl->yTop - (iBoxHeight * 5) / 100; 
if (IPercent) 

Recti.yBottom = Recti.yTop - 

((iBarHeight * (100 - IPercent)) / 100); 

else 

Recti.yBottom = Recti.yTop - iBarHeight; 

Recti.xRight = pRectl->xRight - iWidth; 

ab.IColor = IBackColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_COLOR,0,(PBUNDLE)&ab); 

GpiMove (hPS,(PPOINTL)&Rectl); 

GpiBox (hPSjDRO_FILL,(PPOINTL)&Rectl.xRight,0,0); 

Recti.yTop = Recti.yBottom - 1; 

Recti.yBottom = pRectl->yBottom + (iBoxHeight * 20) / 100; 
ab.IColor = IColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_COLOR,0,(PBUNDLE)&ab); 

GpiMove (hPS,(PPOINTL)&Rectl); 

GpiBox (hPS,DRO_FILL,(PPOINTL)&Rectl.xRight,0,0); 
return (TRUE); 
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BOOL APIENTRY DrawThermometer (HPS hPS,PRECTL pRectl,LONG IStyle, 
LONG IColor, LONG IBackColor, LONG IPercent) 

/*.*\ 

This function will draw the outine of a thermometer scaled to 
the supplied rectangle in the give presentation space. The bulb 
of the rectangle is filled with IColor and the remainder is drawn 
by the DrawTemperature function. 


hPS Presentation space to render in. 

pRectl Bounding box of the thermometer. 

IStyle Currently undefined. 

IColor Color index used to fill bulb and stem of thermometer. 
IBackColor Color to fill the remainder of the stem (100 - IPercent). 
IPercent Amount to fill the thermometer. Valid range is 0 to 100. 

\*.*/ 

{ 


LINEBUNDLE lb; 

AREABUNDLE ab; 

ARCPARAMS arcparms; 

POINTL lPtCenter; 

POINTL IStartPt; 

POINTL lEndPt; 

POINTL lPt; 

FIXED fxStartAngle,fxSweepAngle; 

RECTL BulbRectl; 

int iBoxHeight = pRectl->yTop - pRectl->yBottom; 

/* Calculate the height of the bulb to be 25% of the total height */ 
BulbRectl = *pRectl; 

BulbRectl.yTop = BulbRectl.yBottom + (iBoxHeight * 25) / 100; 

/* define the bounding box for the arc */ 

arcparms.lP = (BulbRectl.xRight - BulbRectl.xLeft) / 2L; 

arcparms.lQ = (BulbRectl.yTop - BulbRectl.yBottom) / 2L; 

arcparms.lR = 0L; 

arcparms.lS = 0L; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 

/* Calculate the center point of bulb */ 
lPtCenter.x = BulbRectl.xLeft + arcparms.lP; 
lPtCenter.y = BulbRectl.yBottom + arcparms.lQ + 1; 

/* . *\ 

Draw the bulb 

\*.*/ 

/* Draw an invisble arc from the current location to the 
start angle */ 

fxStartAngle = MAKEFIXED(120,0); 
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fxSweepAngle = MAKEFIXED(90,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0 j 0)); 

GpiQueryCurrentPosition(hPS,(PPOINTL)&lStartPt); 

/* Draw the left highlighted outline of the bulb */ 

lb. IColor = CLRJVHITE; 

lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R j LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

/* Draw the right shadowed outline of the bulb */ 
fxStartAngle = MAKEFIXED(210,0); 
fxSweepAngle = MAKEFIXED(210,0); 
lb.IColor = CLR_DARKGRAY; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

GpiQueryCurrentPosition(hPS,(PPOINTL)&lEndPt); 

/* Fill the bulb of the thermometer with the supplied color */ 
arcparms.lP ■= 4; 
arcparms.lQ -= 4; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
ab.IColor = IColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_COLOR,0,(PBUNDLE)&ab); 

GpiMove (hPS,&lPtCenter); 

GpiFullArc(hPS, DRO__FILL,MAKEFIXED(1,0)) ; 


/*.*\ 

Draw the reflection on the bulb 

\*...*/ 

arcparms.lP = (arcparms.lP * 3) / 4; 
arcparms.lQ = (arcparms.lQ * 3) / 4; 


GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(120,0); 
fxSweepAngle = MAKEFIXED(90,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0,0)); 

lb. IColor = CLRJVHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R j LBB_TYPE,0,(PBUNDLE)&lb); 
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GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0) 3 fxStartAngle, 
fxSweepAngle); 

arcparms.lP = (arcparms.lP *2) / 3; 
arcparms.lQ = (arcparms.lQ * 2) / 3; 

GpiSetArcParams(hPS 3 (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(120 3 0); 
fxSweepAngle = MAKEFIXED(90 3 0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE 3 LBB_TYPE 3 0 3 (PBUNDLE)&lb); 
GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1 3 0) 3 fxStartAngle 3 
MAKEFIXED(0 3 0)); 

lb.IColor = CLR_WHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS 3 PRIM_LINE 3 LBB_C0L0R | LBB_TYPE 3 0,(PBUNDLE)&lb) ; 
GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0) 3 fxStartAngle, 
fxSweepAngle); 


/*.*\ 

Draw the sides 

\*.*/ 

/* Draw the right vertical side */ 
lb.IColor = CLR_DARKGRAY; 

GpiSetAttrs (hPS 3 PRIM_LINE 3 LBB_COLOR 3 0 3 (PBUNDLE)&lb); 

GpiMove(hPS 3 (PPOINTL)&lEndPt); 
lPt.x = lEndPt.x; 

lPt.y = pRectl->yBottom + ((iBoxHeight * 95) / 100); 

GpiLine (hPS 3 &lPt); 

/* Draw the left vertical side */ 
lb. IColor = CLRJVHITE; 

GpiSetAttrs (hPS,PRIM_LINE 3 LBB_COLOR 3 0 3 (PBUNDLE)&lb); 
lPt.x = IStartPt.x; 

GpiMove(hPS,(PPOINTL)&lPt); 

GpiLine (hPS 3 &lStartPt); 


/*.-.- . *\ 

Draw the rounded top 

\* . */ 

/* Reset the rectangle for drawing the rounded top */ 

BulbRectl.xLeft = IStartPt.x; 

BulbRectl.yBottom = pRectl->yBottom + (iBoxHeight * 90) / 100; 
BulbRectl.xRight = lEndPt.x; 

BulbRectl.yTop = pRectl->yTop; 


arcparms.lP = (BulbRectl.xRight - BulbRectl.xLeft) / 2L; 
arcparms.lQ = (BulbRectl.yTop - BulbRectl.yBottom) / 2L; 
GpiSetArcParams(hPS 3 (PARCPARAMS)&arcparms); 
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/* Calculate the center point for the rounded top arc */ 
lPtCenter.x = BulbRectl.xLeft + arcparms.lP; 
lPtCenter.y = BulbRectl.yBottom + arcparms.lQ + 1; 

/* Draw an invisble arc from the current location to the 
start angle */ 

fxStartAngle = MAKEFIXED(0,0); 
fxSweepAngle = MAKEFIXED(120,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0,0)); 

/* Draw the shaded side */ 
lb.IColor = CLR_DARKGRAY; 
lb.usType = LINETYPE__SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

/* Draw thehighlighed side */ 
fxStartAngle = MAKEFIXED(120,0); 
fxSweepAngle = MAKEFIXED(60,0); 
lb.IColor = CLRJVHITE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_COLOR,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

/* Draw the reflection */ 
arcparms.lP = (arcparms.lP * 3) / 4; 
arcparms.lQ = (arcparms.lQ * 3) / 4; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(90,0); 
fxSweepAngle = MAKEFIXED(90,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0) ,f xStartAngle, 
MAKEFIXED(0,0)); 

lb.IColor = CLR_WHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 


DrawTemperature(hPS,pRectl,IColor,IBackColor,IPercent); 
return (TRUE); 




Introduction 

Throughout this book, we have been outputting text with various Graphics Program¬ 
ming Interface (GPI) functions. We even demonstrated changing the font in Chapter 4, 
“2.1 Common Dialogs,” by selecting a new font in the common font selection dialog. 
The detail of enumerating, creating, scaling, and rendering of fonts has been largely 
ignored. This chapter will focus on all those topics and more. 
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Terminology 

Before beginning, some defections are in order. Knowing the words that describe the 
characteristics of fonts will make your work considerably easier. 

Single-Byte and Double-Byte Characters 

The term “font” appears in this book many times, but what exactly is a font? The term 
originates from printing, where a font describes a collection of characters that share a 
common height, style, and weight of typeface. 

The collection of characters can be of any number in the real world of printing. Most 
computer fonts in the Western world are numbered with a single byte. This means there 
can be no more than 256 characters. The fonts we will be working with in this chapter 
have a single-byte character set (SBCS). 

All the non-Asian languages supported by OS/2 use fonts from a single-byte charac¬ 
ter set. The Japanese, Chinese, and Korean languages use two bytes to represent the thou¬ 
sands of characters and ideographic symbols required by those languages. 

Consequently, they use what is referred to as the double-byte character (DBCS). Using 
two bytes for each character increases the maximum character set from 255 to 65,536. 

Point Size 

The height of a font is described in points, which is short for printer points. 

Each printer point is 1/72 inch. Even with this exact measurement, a point size only 
approximates the height of the characters in the font. The height of the characters are up 
to the designer of the font. 


Font Families 

Fonts are divided into families based on the appearance characteristics of the font. A major 
determinate of a font family is the presence or absence of serifs. A serif is a fine line (rela¬ 
tive to the stroke width) drawn at the end and perpendicular to the major stiokes 
of a character. It often appears as a flaring of the stroke. Fonts without serifs are referred 
to as sans (from the French word without) serif (See Figure 7.1). 

The font on the left has serifs, whereas the font on the right does not. Strokes are the 
lines used to draw the characters of the font. The width of those strokes are also used to 
classify the font into a family. 
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Figure 7.1. 

Sample serif and 
sans serif characters. 


M M 

Serif Sans Serif 


A font family is comprised of one or more fonts with a unique typeface name. The 
word typeface is often used for typeface name. The characters of those fonts will be 
representative of the family to which they belong. The facename for each font within 
a family will be unique, but often will be comprised of a base family name plus attribute 
modifiers. For example, Times New Roman Italic facename is comprised of the family 
name Times New Roman and the modifier Italic. 

Font Rendering 

Font representation and rendering falls into two categories—outline and image. The 
characters of an outline font are described in terms of the graphics arcs and curves that 
draw the font. Image font characters, on the other hand, are bitmaps. Both have advan¬ 
tages and disadvantages. Outline fonts are continuously scalable, may be rotated, sheared, 
and displayed at larger point sizes without a loss of quality. Rotation changes the baseline 
angle against which text is output. 

Shearing occurs when the characters in a font are slanted by modifying the character 
bounding box. An italic font can be thought of as a mildly sheared font. That quality and 
flexibility comes at the expense of speed, however, because each character must be drawn 
when output. The quality of outline fonts is not always superior to image fonts, how¬ 
ever. At smaller sizes, image fonts are often easier to read than an outline font of an equiva¬ 
lent size because they were specifically designed for that size. Image fonts display faster 
than outline fonts because a bitmap exists for each character in the font. To support vari¬ 
ous device resolutions, an image font will require a bitmap for each character in each point 
size for each screen resolution it supports. In our sample program, we will enumerate 
and see all sizes available for each image font. Image fonts may not be scaled, rotated, or 
sheared. 

Both outline and image fonts define characters based on code points. A code point is 
the actual numeric byte value of the character. It is from this value that mapping to the 
actual glyph displayed on output begins. For example, the code point 65 maps to the 
character glyph A in all single-byte character set code pages. A glyph is the picture or 
symbol associated with a given code point. When we said that single-byte character set 
fonts may define up to 256 characters, we were referring to the number of glyphs that 
can be represented; therefore, although all single-byte character set fonts will have 256 
code points, it is not required that a glyph be defined for all of them. For example, a font 
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that is decorative or ornamental may not define the block drawing characters. The map¬ 
ping between code point and a character glyph is referred to as a code page. A code page 
may be based on either ASCII or EBCDIC. OS/2 defines many code pages for the 
application’s use. Figure 7.2 demonstrates a single-code point (8E) being mapped into 
three different character glyphs. 


Figure 7.2. 
Code point to 
glyph mapping. 


Code Point 



ASCII Multilingual ASCII French-Canadian EBCDIC US-English 
Code Page 850 Code Page 863 Code Page 037 


Correct use of code pages is important to interacting with other applications and the 
system. 

Style attributes may be applied to both outline and image fonts. Bold and italic are 
the most commonly used attributes. Again, outline and image fonts differ in the method 
by which these attributes are implemented for a font. What is normally thought of as a 
single outline font by the end user is often made up of a set of four fonts, one for each of 
the attribute combinations. For example, the Times New Roman font family is composed 
of the following four fonts: 

Times New Roman Base font. 

Times New Roman Bold Base font with embolding. 

Times New Roman Bold Italic Base font with embolding and italic. 

Times New Roman Italic Base font with italic. 

Each font from this family is a separate physical resource, but applications often present 
them to the user as a single-font resource that can be made bold, italic, or both. The 
common font selection dialog discussed in Chapter 4 shows the font family name in the 
first combo box and a style that can be applied to that font in a separate combo box. 
Notice that the family name is not always the same as the base font facename. Unlike 
outline fonts, an image font does not include separate physical resources for each attribute 
combination desired. Image fonts can be made bold, italic, or bold italic by synthesizing 
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the appearance desired. PM will create a character glyph based on the original bitmap. A 
bold font may be created by double-striking the base font at an offset in the X direction. 
Italics may be simulated by progressively offsetting the bits of the character starting at 
the bottom of the character. 

Default Font 

In many of the sample programs in this book, text was output by using one of the GPI 
output functions without setting or changing a font. Setting a font is not required 
because each presentation space has a default font resource set into it. When you call 
WinGetPS, WinBeginPaint, or GpiCreatePS, the default System Proportional font is 
set into that presentation space before returning. The System Proportional font is an image 
font supplied by the display driver to approximate a 12-point font based on the screen 
resolution of the device. 

Text Output Functions 

PM supplies a group of functions that enables you to output character strings, using its 
currently selected font attributes. With the exception of the WinDrawText function, all 
GPI text output functions are limited to 512 characters. The GPI text function can be 
split into two groups, those with formatting and those without. In each group, one al¬ 
lows the current position to be specified and the other does not. 

Nonformatting: 

GpiCharString Outputs a character string at the current location. 

GpiCharStringAt Outputs a character string starting at a supplied 

location. 

Formatting: 

GpiCharStringPos Outputs a character string at the current location using 
a set of supplied formatting options. 

GpiCharStringPosAt Outputs a character string starting at a supplied 

location using a set of supplied formatting options. 
WinDrawText Outputs a character string in a bounding rectangle 

using a set of supplied formatting options. 

Regardless of how the starting point is defined, all the GPI functions position the 
character string based on the character reference point. This point is defined as the inter¬ 
section of the baseline and the vertical line that defines the left character cell boundary. 
As you can see in Figure 7.3, descenders are drawn below the reference point and ascend¬ 
ers are drawn above it. 


■ 
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Figure 73. 
Character 
reference point. 
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The GpiCharString function is the most basic of all character primitives. Text is 
output starting at the current location, and the current position is updated after each 
character is output. A starting position is not supplied. The GpiCharStringAt function 
is identical except it enables you to supply your own starting point. To best utilize these 
functions in your application, some thought is required. For example, if you are output¬ 
ting multiple lines of text with no breaks or style changes in a line, it would be more 
efficient to use the GpiCharStringAt function to specify the starting position of each 
line. If a line of text includes a mixture of font styles, however, the first text style on a line 
could still be output by using the GpiCharStringAt function and the remainder of the 
line rendered with the GpiCharString function. Because the current position is updated 
when the characters are drawn, it would not be necessary to query the current location 
before outputting the second and subsequent text styles: 

GpiCharStringAt (hPS,pPtl,ICount,pchString) 

HPS hPS Handle of the presentation space to render the 

characters into. 

PPOINTL pPtl Pointer to the point where text output will begin. 

LONG ICount Length in bytes of the memory pointed to by 

pchString—the maximum is 512. 

PCH pchString Pointer to a null-terminated string to output. 

Expanding on basic text output function are the GpiCharStringPos and 
GpiCharStringPosAt functions. These two functions add formatting options to the 
previous functions giving the caller greater flexibility over the display of characters. 

GpiCharStringPosAt (hPS,pPtl,pRectl,lOptions,ICount,pchString,paDX) 
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PRECTL 

pRectl 

Pointer to a bounding and/or clipping 
rectangle to be used if the CF1S_CLIP 
or CHS_OPAQUE options are speci¬ 
fied. Otherwise, the parameter is 
ignored. 

LONG 

lOptions 

Flags that control the formatting of the 
output. It may be one or more of the 
following: 


CHS_CLIP 

Clips the text drawn to the supplied 
rectangle defined by pRectl. 


CHSJLEAVEPOS 

The current position is not updated. 
Without this flag, the current GPI 
position will be updated to the character 
reference point for where the next char¬ 
acter would have been drawn. 


CHS_OPAQUE 

The rectangle defined by pRectl is filled 
with the current background color in 
the CHARBUNDLE. This color may be 
set by Calling GpiSetBackColor or 
GpiSetAttrs. 


CHS_STRIKEOUT 

The text string is drawn overstruck. 


CHS_UNDERSCORE 

The text string is drawn underscored. 


CHS_VECTOR 

This flag indicates that the paDX pa¬ 
rameter contains pointer to an array of 
longs which supply incremental value to 
be used when spacing characters. 

PLONG 

paDX 

Pointer to an array of longs used to 
position characters in the text string. 

This parameter is ignored if the 
CHS_VECTOR option flag is not used. 


The CHS_OPAQUE option enables you to specify a rectangle to be filled with the cur¬ 
rent CHARBUNDLE background color. Notice that the rectangle can be independent of the 
location where the text is drawn. Two functions are available to set the background color. 
GpiSetBackColor will set the background color in all bundles, and GpiSetAttrs can 
set the background color only of the CHARBUNDLE. For example, set a red background fill 
as follows: 

GpiSetBackColor (hPS,CLR_RED); 

or set the background color in the CHARBUNDLE as follows: 

CHARBUNDLE cb; 
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cb.IBackColor = CLR_RED; 

GpiSetAtt rs(hPS,PRIM_CHAR,CBB_BACK_COLOR,0,(PBUNDLE)&cb); 

Text Extents and Spacing 

Text output by the GPI functions are also affected by the direction, spacing, and align¬ 
ment values set into a presentation space. Character direction controls the direction char¬ 
acters are output. The default is to output characters left: to right along the baseline. The 
GpiSetCharDirection function enables you to change the horizontal direction to right 
to left or to output characters vertically. Vertical text is drawn either top to bottom or 
bottom to top along a line perpendicular to the baseline. The character reference point 
for vertical text is the center of the character cell as opposed to the left side of the cell 
used for horizontal text. 

One method of altering the spacing of characters in a text string may be controlled 
by supplying an array of increment values to one of the GPI formatting text functions. 
This is useful if the increment value from character to character is modified in a nonlin¬ 
ear fashion. If the spacing of all characters output needs to be modified uniformly, how¬ 
ever, the GpiSetCharExtra or GpiSetCharBreakExtra functions may be used. Each 
function takes a fixed value that modifies the default spacing. The GpiCharExtra func¬ 
tion modifies the spacing of all characters, whereas GpiSetCharBreakExtra changes only 
the spacing of the break character. The break character is defined by the font and may be 
retrieved from the sBreakChar field of the FONTMETRIC structure. This character is of¬ 
ten, but not always, the space character. The break value may be negative or positive. 
Negative values result in less space between characters, and positive values result in more 
space between characters. The break character will be affected by the character spacing 
and break character spacing. For example, if the character spacing was increased by one, 
but the break character spacing was decreased by one, there would be no effective change 
to the break character spacing. 

In the sample application for this chapter, PMFONT, the character Extra and Break 
Character Extra for the selected font may be modified. Select the Rotation/Shear menu 
option on the display pop-up menu. Two slider controls enable you to dynamically modify 
the spacing of the current ext wstring. Table 7.1 defines the default presentation space 
attributes that affect text output. 


Table 7.1. Default values that affect text. 

Character Attribute Default Function(s) to Query I Modify 


Angle 


TO 


GpiSetCharAngle 
GpiQueryCharAngle 
GpiSetAttrs CBB_ANGLE 
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Character Attribute 

Default 

Function(s) to Query/Modify 

Shear 

0,1 

GpiSetCharShear 

GpiQueryCharShear 

GpiSetAttrs CBB_SHEAR 

Direction 

left to right 

GpiSetCharDirection 

GpiQueryCharDirection 

GpiSetAttrs CBB_DIRECTION 

Mode 

CH_MODEl 

GpiSetCharMode 

GpiQueryCharMode 

GpiSetAttrs CBB_MODE 

Extra spacing all 
characters 

zero 

GpiSetCharExtra 

GpiQueryCharExtra 

GpiSetAttrs CBB_EXTRA 

Extra spacing break 
character only 

zero 

Gp iS e t Char B r eakExtr a 
GpiQueryCharBreakExtra 

GpiSetAttrs CBB_BREAK_EXTRA 

Foreground (text) 
color 

CLRJBLACK 

GpiSetAttrs CBB_COLOR 

Background color 

DISPLAY_SYSCLR_WINDOW 

GpiSetAtts CBB_BACK_COLOR 
PRINTER_PAPER_COLOR 

Foreground (text) 
mix mode 

FM_OVERPAINT 

GpiSetAttrs CBB_MIX_MODE 

Background 
mix mode 

BMJLEAVEALONE 

GpiSetAttrs 

CBB_BACK_MIX_MODE 


Common Dialog 

Chapter 4 discussed using the common font selection dialog. It allows an application to 
add font selection quickly to an application. Choosing the font is only half the story, 
however. Creating and using a font requires you to know much that the common font 
dialog hides from you. In an effort to focus on the font dialog and not fonts, the sample 
program in Chapter 4 was limited in scope. It enabled you to select only from image 
fonts when changing the font used to display the text of the file. It also ignored how fonts 
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were enumerated by PM and shown in the dialog. It gave you a taste of dealing with fonts, 
but left out the details. It’s now time for the details. 

Enumeration 

You may be wondering where the common dialog got the font information to display in 
the combo boxes. All the items displayed were enumerated by PM to the dialog by call¬ 
ing the GpiQueryFonts function. The GpiQueryFonts function returns information about 
the font resources available to the application through the FONTMETRICS structure: 

GpiQueryFonts (hPS,lOptions,pszFacename,plCount,IMetricLength, 
pFontMetrics) 


HPS 

hPS 

Presentation space handle for 
the device to enumerate 
FONTMETRICS from. 

LONG 

lOptions 

Flags that control what type of 
font resources are included in 
the enumeration. It may be one 
or more of the following: 


QFJPUBLIC 

Return fonts that are available to 
all processes. This includes fonts 
loaded using the GpiLoadPublic- 
Fonts function. 


QF_PRIVATE 

Return fonts that have been 
loaded by calling GpiLoadFonts 
and are available only to the 
current process. If this flag is 
used alone and no private fonts 
have been loaded, no fonts will 
be returned by this function. 


QF_NO_DEVICE 

Return fonts that are not device 
specific. 


QF_N 0_GENERIC 

Return fonts that are not device 
independent. 

PSZ 

pszFacename 

Pointer to a null-terminated 
string that contains the font 
typeface name. 

PLONG 

plCount 

Pointer to a long that contains 
the number of fonts to enumer¬ 
ate. The pFontMetrics parameter 
should be at least IMetricLength 
* (plCount) bytes long. 
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LONG IMEtricLength Length in bytes of the 

FONTMETRICS 
structure to be returned, 
sizeof(FONTMETRICS) 
is often used. 

PFONTMETRICS pFontMetrics Pointer of the buffer to copy 

the requested array of 
FONTMETRICS to. 

To determine the memory requirements for the desired set of fonts, the 
GpiQueryFonts function should be called with the lOptions and pszFaceriame set to 
the desired values and the contents ofplCount and the pFontMetrics parameter set to 
zero. The return value will indicate the number of fonts meeting the search criteria. 
Memory can then be allocated for the size of the FONTMETRICS structure times the num¬ 
ber of fonts. After the memory is allocated, calling GpiQueryFonts a second time with 
the contents of plCount set to the number of fonts returned on the first call and 
pFontMetrics pointing to the allocated memory, an array of FONTMETRICS structures 
will be returned. This structure contains all the detailed information necessary to create 
and manipulate the font. To give you a feel for the contents of the FONTMETRICS, the 
sample application in this chapter, PMFONT, will enumerate all the public and private 
fonts available and place the facename of the font in a list box. The names are added to 
the list box in the order they were received from PM. When the font is selected in the list 
box, the FONTMETRICS for that font are displayed along with a sample text string in the 
client window. The result is a font browser of sorts. 

First, we must establish the number of fonts available: 

ulCount = GpiQueryFonts (hPS,QF_PUBLIC | QF_PRIVATE,NULL, 

&ulCount,(LONG)sizeof(FONTMETRICS),0); 

If at least one font exists, memory is allocated and the fonts queried and then added 
to the list box. 

if (ulCount) 

{ 

DosAllocMem ((PPVOID)&pFontMetrics,sizeof(FONTMETRICS) * 
(USHORT)ulCount, 

OBJJTILE | PAG_READ | PAGJVRITE | PAG_COMMIT) ; 

GpiQueryFonts (hPS,QF_PUBLIC | QF_PRIVATE,NULL, 

&ulCount,(LONG)sizeof(FONTMETRICS),pFontMetrics); 

WinSendMsg (hLBox,LM_DELETEALL,NULL,NULL); 

for (i = 0; i < (int)ulCount; i++) 

{ 
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WinSendMsg (hLBox,LM_INSERTITEM,(MPARAM)LIT_END, 

(MPARAM)(pFontMetrics+i)->szFacename); 

} 

} 

return (pFontMetrics); 

The client window of PMFONT is split vertically into two components. On the left 
side are the selection and information windows. The right side will be used to show a 
sample of the currently selected font. A list box is created to hold the font facenames of 
the enumerated fonts. It is created as a child of the client window and positioned in the 
upper-left corner of the screen. The client window is also the owner window so that it 
will receive command and notification messages when a change in the list box selection 
is made. 

The list box is displayed continually, and other “panel” windows are displayed below 
it. We define a panel window to be one that is part of a group of interchangeable win¬ 
dows that have the same size and are displayed at the same screen location. Although they 
are displayed at the same screen location, only one is visible at any point in time. Typi¬ 
cally, a different panel will be used for each mode of operation. Each panel will have one 
or more children that display information and allow data entry. You might be thinking 
that a panel sounds a lot like a dialog; well it is, and it isn’t. 

Dialogs are an excellent way to group a feature or function of a program, but they 
can break the work flow of your application. A panel is created from a dialog template, 
but it is displayed as a part of the main application. Using the dialog template eliminates 
the cumbersome process of creating all the display windows individually. When the panel 
contains children that will accept focus, the default dialog procedure will process tabbing 
between windows for you. The panel is simply replaced with a new one when the opera¬ 
tion mode of the program changes. Our first panel displays the FONTMETRICS for the 
selected font. 

The FONTMETRICS Structure 

The FONTMETRICS structure contains many fields that define the sizes, attributes, and 
descriptions of fonts. The characters of a font reside in a rectangle referred to as a cell. 
Each cell has a width and height, and the character must reside entirely within the cell. 
Along the bottom quarter of the cell is a horizontal line known as the baseline. The baseline 
is the logical line defining where the base of a character rests when drawn. The part 
of the character drawn above the baseline is the ascent, and that drawn below is the 
descent. Characters such as lowercase g, q, p, and j have descent and ascent, whereas 
most uppercase characters have only ascent. Figure 7.4 depicts ascent and descent for two 
characters. 
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Figure 7.4. 
Character ascent 
and descent. 
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It might prove useful to run the PMFONT program and examine the contents of 
the metrics on your machine while we are describing the fields of the FONTMETRICS struc¬ 
ture. The fields in boldface type are displayed in the FONTMETRICS panel of the 
PMFONT program. Sample output is depicted in Figure 7.5. 


Figure 7.5. 

PMFONT application. 
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CHAR szFamilyname 


CHAR szFacename 


USHORT idRegistry 
USHORT usCodePage 


A null-terminated character array of 
FACESIZE length that will contain the font 
family name. FACESIZE is currently 
defined as 32. Do not, however, rely on 
this; use FACESIZE when sizing arrays. 

A null-terminated character array of 
FACESIZE length that contains the 
facename of the font. The maximum length 
(FACESIZE -1) is adequate for the fonts 
shipped with OS/2, but too short for some 
of the Adobe type Is that may be installed. 
For compatibility with older PM applica¬ 
tions (l.X), szFamilyname and szFacename 
remain unchanged, but two new fields have 
been added to the FONTMETRICS 
structure. 

The FamilyNameAtom and 
FaceNameAtom fields will contain atoms if 
the font facename or family name exceeds 
FACESIZE -1. If this occurs, the 
FM_TYPE_ATOMS flag will be set in the 
usType field. Your application should check 
this flag and retrieve the atom text for the 
family and facename, rather than use the 
contents of the szFamilyname and 
szFacename fields. 

The IBM registered number. This field 
serves little or no value to an application. 
This field indicates which code page or code 
pages are supported by this font. You may 
recall that a code page defines the mapping 
between code points and character glyphs. It 
may be one of the following: 

0 All code pages are supported. 

65400 The font is special purpose or 

decorative and does not support 
any defined code page. The 
Symbol Set font shipped with 
OS/2 reports this code page, 
other The code page supported by the 

font. 
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LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 


LONG 


LONG 


LONG 

LONG 

LONG 


lEmHeight 
1XH eight 
IMaxAscender 

IMaxDescender 

lLowerCaseAscent 

lLowerCaseDescent 

llnternalLeading 


lExternalLeading 


lAveCharWidth 


IMaxCharInc 

lEmlnc 

IMaxBaselineExt 


This field contains the font point size in 
world coordinates. 

This field contains the average ascent of the 
lowercase characters in the font. 

This field contains the maximum height 
above the baseline for any character in the 
font. The character, however, is not 
identified. 

This field contains the maximum depth 
below the baseline for any character in the 
font. As with the IMaxAscender, the 
character is not identified. 

This field contains the height of the tallest 
unaccented lowercase character in the font. 
This field contains the maximum depth 
below the baseline for any unaccented 
lowercase character in the font. 

This field defines the space reserved at the 
top of the character cell for diacritics. 
Diacritics are accent marks that appear 
above a character. See Figure 7.4 as an 
example. This value is included 
in the IMaxAscender value. 

This field contains a recommended amount 
of additional space to be used between lines 
of text rendered with this font. This value is 
not part of the character cell and all PM 
supplied fonts set this field to 0. Your 
application should consider using this value 
when spacing lines of text. 

This field contains the average width of the 
characters in the font based on their 
occurrence in the English language. For 
fixed pitch fonts, this value will be the actual 
width of each character cell and may be used 
for advancing caret and insertion points. 
This field is the cell width of the widest 
characters in the font. 

This field contains the width of the EM 
square. 

This field contains the sum of the 
IMaxAscender and IMaxDecender fields. 
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SHORT sCharSlope This field contains the angle that a font 

slants from an imaginary line perpendicular 
to the baseline (see Figure 7.6). The angle is 
measured clockwise in degrees and minutes 
from this imaginary line. Degrees are stored 
in bits 0 through 9. Minutes are stored in 
bits 10 through 15. Bit 16 is unused. 


Figure 7.6. 
Character slope. 



SHORT slnlineDir This field contains an angle that determines 

the direction of output relative to the 
current position (see Figure 7.7). The angle 
is measured in degrees and minutes counter¬ 
clockwise from the baseline. Fonts that are 
designed to be output left to right will have 
an angle of 0 degrees. Those intended to be 
output right to left will have an angle of 180 
degrees. 


Figure 7.7. 
Inline direction. 



32 0 



Chapter / Creating and Manipulating PM Fonts and Text 


SHORT sCharRot This field contains the angle that determines the 

rotation of the character glyphs to the default 
baseline (see Figure 7.8). The angle is measured 
in degrees and minutes counter-clockwise from 
that baseline. It is this angle that the characters 
use as a baseline. 


Figure 7 . 8. 
Character rotation. 



0 degree Character Rotation 



45 degree Character Rotation 


USHORT usWeightClass This field contains a value that classifies the 

stroke width of a font. There are currently 
nine weight classes defined: 

FWEIGHT_DONT_CARE 

FWEIGHT_ULTRA_LIGHT 

FWEIGHT_EXTRA_LIGHT 

FWEIGHT_LIGHT 

FWEIGHT_SEMI_LIGHT 

FWEIGHT_NORMAL 
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FWEIGHT_SEMI_BOLD 

FWEIGHTJBOLD 

FWEIGHT_EXTRA_BOLD 

FWEIGHT_ULTRA_BOLD 

Most fonts will fall into the light, normal, or 
bold weight classes. 

USHORT usWidthClass This field contains a value that classifies the 

character cell width of characters in this font 
based on other fonts of this type. The value 
identifies how the width of this font differs 
from the norm. Each flag represents a 
deviation percentage from the norm. The 
width class does not factor in the stroke 


width of the characters: 

FWIDTH_ULTRA_CONDENSED -50.0% 

FWIDTH_EXTRA_CONDENSED -37.5% 

FWIDTH_CONDENSED -25.0% 

FWIDTH_SEMI_CONDENSED -12.5% 

FWIDTH_N ORMAL Reference 

FWIDTH_SEMI_EXPANDED +12.5% 

FWIDTH_EXPANDED +25.0% 

FWIDTH_EXTRA_EXPANDED +37.5% 

FWIDTH_ULTRA_EXPANDED +50.0% 


SHORT sXDeviceRes This field contains information on the 

horizontal resolution of the characters 
in the font. If the usDefn field has the 
FM_DEFN_OUTINE flag set, the value is 
the resolution at which the font was defined, 
or scanned. For outline fonts, this informa¬ 
tion is not useful. Otherwise, the font is an 
image font, and the value is the X resolution 
of the device the font was designed to be 
displayed on. The resolution is measured 
in pels per inch. The X resolution of the 
current device may be determined by calling 
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SHORT sYDeviceRes 


SHORT sFirstChar 

SHORT sLastChar 

SHORT sDefaultChar 


SHORT sBreakChar 


the DevQueryCaps function with the 
CAPS_HORIZONTAL_FONT_RES flag. 

The horizontal device resolution is also 
measured in pels per inch. 

This field contains information on the 
vertical resolution of the characters 
in the font. If the usDefn field has the 
FM_DEFN_OUTINE flag set, the value is 
the resolution at which the font was defined 
or scanned. For outline fonts, this informa¬ 
tion is not useful. Otherwise, the font is an 
image font and the value is the Y resolution 
of the device the font was designed to be 
displayed on. The resolution is measured 
in pels per inch. The Y resolution of the 
current device may be determined by calling 
the DevQueryCaps function with the 
CAPS_VERTICAL_FONT_RES flag. The 
vertical device resolution is also measured 
in pels per inch. 

This field contains the code point of the first 
character in the font. 

This field contains the code point of the last 
character in the font. 

This field defines the default code point for 
the font. When a code point outside the 
range of sFirstChar and sLastChar is 
specified, a replacement value must be 
supplied. This value identifies that point as 
an offset from sFirstCharacter, for example, 
sDefaultCodePoint = sFirstChar + 
sDefaultChar. 

This field defines the offset from sFirstChar 
of the “break” codepoint. This value when 
added to sFirstChar typically identifies the 
code point of the space character. 
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sNominalPointSize 

This field contains information 
on the intended height values for 
the font. If the usDefn field has 
the FM_DEFN_OUTINE flag 
set, the value is the height in 
decipoints (1/720 inch) of the 
intended height. Otherwise, the 
font is an image font, and this 
field contains the height. 

SHORT 

sMinimumPointSize 

These two fields contain a recom¬ 

SHORT 

sMaximumPointSize 

mended minimum and maximum 
point size value for this font. The 
value is set by the font creator 
and factors in the complexity 
of the font. As with the 
sNominalPointSize field, the 
value is measured in decipoints. 

USHORT 

usType 

This field contains type informa¬ 
tion about the font: 


FM_TYPE_FIXED 

The spacing between all characters 
in the font is constant. 


FM_TYPE_LICENSED 

The font is licensed. 


FM_TYPE_KERNING 

The font contains kerning 
information. The number of 
kerning pairs for the font will be 
set in the sKerningPairs field. 

The actual kerning pairs may 
be retrieved by calling the 
GpiQueryKerningPairs function 
when the font is set into a 
presentation space. 


FM_TYPE_DBCS 

The font is for double-byte code 
pages. 


FM_TYPE_MBCS 

The font is for a mixed single- and 
double-byte code page. 


FM_TYPE_64K 

Font exceeds 65,536 bytes. 


FM_TYPE_FACETRUNC 

324 

The font facename exceeds 
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USHORT 


USHORT 


FACESIZE-Rand the 
szFacename field does not contain 
the entire facename of the font. 

FM_TYPE_FAMTRUNC The font family name exceeds 

FACESIZE -1, and the 
szFamilyname field does not 
contain the entire family name of 
the font. 

FM_TYPE_ATOMS The contents of the 

FaceNameAtom and 
FaceNameAtom contain valid 
atoms. 

usDefn This field contains the flag that 

identifies the origin and represen¬ 
tation of the font: 

FM_DEFN_OUTLINE The font is an outline font. If this 

bit is not set, it is an image font. 
FM_DEFN_GENERIC The font is understood by GPI 

and can be rendered on all 
devices. If this bit is not set, it 
is a device specific font. 

fsSelection This field contains flags that 

describe the attributes of this font. 
The flags will reflect only the 
attributes of the physical font, for 
example, outline fonts that 
typically provide four fonts with 
the following physical attributes 
normal, bold, italic, and bold 
italic. Image fonts, on the other 
hand, almost always have synthe¬ 
sized font attributes and, there¬ 
fore, will infrequently have these 
flags set: 

FM_SEL_ITALIC The font is italic. 

FM_SEL_UNDERSCORE The font is underscored. 

Fh4_SEL_NEGATIVE The font has foreground and 

background colors reversed. 
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USHORT 


LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 


LONG 


FM_SEL_OUTLINE 

FM_SEL_STRIKEOUT 

FM_SEL_BOLD 
us Cap abilities 


0 

1 

2 

3 

4 


lSubscriptXSize 

lSubscriptYSize 

lSuperscriptXSize 

lSuperscriptYSize 

lSubscriptXOffset 

lSubscriptYOfFset 

lSuperscriptXOfFset 

lSuperscriptYOffset 

lUnderscoreSize 

IStrikeoutSize 


lUndersco rePosition 


The font is designed with hollow 
characters. 

The font has a strikeout as part of 
the character glyphs. 

The font is bold. 

This field indicates that the 
characters of the font may not be 
mixed with graphics if the 
FM_CAP_NOMIX flag is set. 
The high byte of the field 
identifies the quality of the font. 
There are no system constants 
defined for these values, and the 
value is almost never set to a value 
other than undefined: 

Undefined 

Data processing quality 
Data processing draft quality 
Near letter quality 
Letter quality 

These fields contain the recom¬ 
mended width and height for 
subscripts and superscripts. 


These fields contain the recom¬ 
mended X and Y offset for 
subscripts and superscripts 
relative to the baseline. 


This field contains the height of 
the underscore or strikeout stroke 
for the font. 

This field contains the vertical 
position of the underscore relative 
to the baseline. Positive values are 
below the baseline and negative 
values are above the baseline. 
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LONG 

SHORT 

SHORT 

ATOM 

ATOM 

LONG 


IStrikeoutPosition 

This field contains the vertical 
position of the strikeout relative 
to the baseline. 

sKerningPairs 

This field contains the number 
of character pairs in the table of 
kerning pairs. To retrieve the 
character pairs, the font must be 
created and set into a presentation 
space. When this is done, the 
GpiQueryKerningPairs function 
is called to retrieve an array of 
kerning pairs. 

sFamilyClass 

This field is intended to identify 
a font into a class and subclass. 

The specification was never 
widely published and is largely 
unimplemented by device fonts. 
The least significant byte identifies 
the family class, whereas the most 
significant byte contains the 
subclass. 

FamilyN ameAtom 

When the facename and/or 

F aceN ameAtom 

family name exceed FACESIZE 
-1 bytes in length, the 
FM_TYPE_ATOMS flag will be 
set in the usType field, and these 
two fields will contain atom 
handles for the complete 
facename. 

IMatch 

This field contains a unique ID 
for fonts enumerated from a given 
device at a given time. For example, 
all fonts enumerated from the 
display device will have a unique 
ID. If the value is greater than 0, 
the font is a generic GPI font; if 
negative, it is a device font. The 
IMatch field has no other signifi¬ 
cance and should not be saved (in a 
file, for example) along with other 
font selection information. 
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PANOSE panose This structure identifies the 

PANOSE classification of the 
font. This classification system has 
superseded the sFamilyClass as a 
numeric means of selecting a font 
based on typographical character¬ 
istics. The PANOSE structure 
contains the following fields: 

bFamilyType 
bSerifStyle 
bWeight 
bProportion 
bContrast 
bStrokeVariation 
bArmStyle 
bLetterform 
bMidline 
bXH eight 
ab Reserved [2] 

As you look through the fonts enumerated in the list box, you will see many entries 
with the same name. This occurs primarily in image fonts that must have bitmaps for 
many point sizes and screen resolutions. Because we requested all public and private fonts, 
even imaged fonts that were not designed for this resolution are returned. Your applica¬ 
tion may eliminate these fonts by comparing the sXDeviceRes and xYDeviceRes fields 
of the FONTMETRICS structure to the horizontal and vertical pels per inch for your device. 
Those that do not match their respective values may be eliminated. For example, if your 
application is running on an 8514/A or XGA device at 1024x768, the horizontal and 
vertical resolution will be 120 pels per inch. Fonts that are designed for the standard VGA 
resolution (640 by 480) will have a horizontal and vertical resolution or 96 pels per inch. 

When a font is selected in the list box, the contents of the FONTMETRICS panel are 
updated with the metrics for that font. Some of the items are converted from a numeric 
index to a string. For example, the weight and width values are displayed as the strings 
that describe those values. After updating the metrics, two text strings are output on the 
right side of the client area. The first, displayed in the upper third of the client, is com¬ 
prised of the code points for the character glyphs from “a” to “z” in both uppercase and 
lowercase. The second string, displayed in the lower third of the client, contains the code 
points from 160 to 175. These values were selected to illustrate the variation of character 
glyphs based on the code page with which the font was created. We will elaborate on 
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code pages a bit later; for now, all fonts will be created using the multilingual code page 
850. Image fonts that are selected are displayed at their actual size, and outline fonts are 
displayed in their default size. 

Creating Fonts 

Before we can use any of the physical fonts available on this device, we must create a 
logical font resource and set that resource into a presentation space. A logical font is 
a description of a desired font from which PM will select a physical font. The font 
description is comprised of the facename, size, and attributes of a desired font. The cre¬ 
ation of a logical font can be approached in two ways: You can do the mapping, or PM 
can do the mapping. Font mapping is a process of selecting a font from the available fonts 
that is the “best or closest match” to a requested font. Doing your own font mapping 
requires you to enumerate the available fonts, select the desired font, and create that font 
using values from the FONTMETRICS structure. When you let PM do the font mapping, 
you must simply supply the desired size and style information. The function to create a 
logical font is GpiCreateLogFont. You will notice that input parameter is not a pointer 
to a FONTMETRICS structure, but a pointer to a FATTRS structure. The FATTRS structure 
can be thought of as a subset of the FONTMETRICS structure: 

GpiCreateLogFont (hPS,pName,ILcid,pFattrs) 


HPS 

hPS 

Presentation space handle in which 
to create the logical font resource. 

PSTR8 

pName 

Pointer to a null-terminated 
8-character string that aids in 
description of a logical font. 

LONG 

ILcid 

The local identifier used to refer to 
this font in this presentation space. 
Even though this parameter is a 
long, it must be in the range of 1 
to 254. Because bitmap resources 
are also referred to by a local 
identifier, this value may not be 
the same as a currently defined 
bitmap LCID. 

PFATTRS 

Fattrs 

Pointer to a FATTRS structure that 
describes the font to be created. 


The GpiCreateLogFont function uses the contents of the supplied FATTRS struc¬ 
ture as searching criteria to select a font. As mentioned, the FATTRS is a subset of the 
FONTMETRICS structure. Let’s look at the FATTRS structure. 
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USHORT 

usRecordLength 

The length in bytes of the 

FATTRS structure. 

USHORT 

fsSelection 

This parameter does not affect the 
font selection but the style to be 
applied to the selected font: 


FATTR_SEL_ITALIC 

Makes the font italic. 


FATTR_SEL_UNDERSCORE 

Underscores the characters. 


FATTR_SEL_STRIKEOUT 

Overstrikes the characters. 


FATTR_SEL_BOLD 

Emboldens the characters. 


FATTR_SEL_OUTLINE 

Does not fill outline characters. 

This flag has no effect on image 
fonts. 

LONG 

IMatch 

The font match identifier returned 
as the IMatch field of the 
FONTMETRIC structure. The 
match value is only valid for the 
device from which it was enumer¬ 
ated. Negative IMatch values indi¬ 
cate a device font. If IMatch is set 
to 0, PM attempts to select a font 
that meets the desired criteria. 

CHAR 

szFacename 

A null-terminated character string 
of length FACESIZE that identi¬ 
fies the facename of the desired 
font. This is equivalent to the 
szFacename in the 

FONTMETRIC structure. 

USHORT 

idRegistry 

The IBM registered number. 

USHORT 

usCodePage 

The desired code page to use when 
creating the font. The default code 
page is used if 0 is specified. The 
current code page may be retrieved 
by calling the GpiQueryCp 
function. This value should 
generally be equal to the message 
queue code page. 

LONG 

IMaxBaselineExt 

• • * W 
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If the fsFontUse parameter 
does not have the 
FATTR_FONTUSE_OUTLINE 
flag set, this field contains the 
height of the requested image font. 
Otherwise, it should be set to 0. 
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LONG 

lAveCharWidth 

If the fsFontUse parameter 
does not have the 

FATTRJFONTUSEJDU^ 

flag set, this field contains the 
width of the requested image 
font. Otherwise, it should be 
set to 0. 

USHORT 

fsType 

Defines the required font 
type: 


FATTR_TYPE_KERNING 

A kerned font is required. 


FATTR_TYPE_MBCS 

Mixed single- and double¬ 
byte code page required. 


FATTR_TYPE_DBCS 

Double-byte code page 
required. 


FATTR_TYPE_ANTIALIASED 

Antialiased font required. 

USHORT 

fsFontUse 

Defines the intended use of 
the font: 


FATTR_FONTUSE_NOMIX 

Text is not output with 
graphics. 


FATTR_FONTUSE_OUTLINE 

An outline font is required. 


FATTR_FONTUSE_TRANSFORMABLE 

Characters must be scalable, 


shearable, and scalable. 

If the function fails, it will return GPI_ERR0R; otherwise, it will return the result of 
the creation. If FONT_MATCH is returned, the supplied LCID now refers to a font match¬ 
ing your selection criteria. If FONT_DEFAULT is returned, a match was not found, and the 
default font has been selected. For display devices, the default will be the System Propor¬ 
tional Font. 

To perform your font mapping, you may select a font based on enumerated font 
metrics. The OS/2 documentation says that a font may be selected by setting only the 
IMatch and the usRecordLength fields in the FATTRS. While developing the sample 
application for this chapter, we were unable to create a font based on the IMatch and 
usRecordlength fields alone. The default font was selected even if the same presenta¬ 
tion space handle was used for the enumeration and creation. When the szFace name 
from the FONTMETRICS szFacename was added, the desired font was successfully created. 
We, therefore, recommend that when creating a logical font, the FATTRS structure should 
be initialized with as much information as possible, even if you have a IMatch value. 

If the IMatch field is set to 0, PM will attempt to select a font matching the supplied 
criteria. The chart in Figure 7.9 is a simplified description of the font selection process. 
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Figure 7.9. 

Font mapping flowchart. 


PM Font Mapping 



Notice that if an image font of the desired width and height is not found, an outline 
font may be substituted for it. 

If the GpiCreateLogFont function was successful, the LCID for the font can now 
be set into a presentation space. The LCID can be thought of as an application-defined 
local handle that can be selected and unselected in a presentation space. The 
GpiSetCharSet function will “select” the supplied LCID into the supplied presentation 
space: 

GpiSetCharSet (hPS,ILcid) 

HPS hPS Presentation space handle to select ILcid into. This must be 
the same handle passed to the GpiCreateLogFont function 
when the local identifier was created. 

LONG ILcid The local identifier used to refer to the font. To reset the 
default, use LCID_DEFAULT. 

This font will now be used for all text output and query functions. When you are 
finished with a font resource, it should be freed. If the resource is currently set into a 
presentation space, the default value should be restored by calling the GpiSetCharSet 
function that is using LCID_DEFAULT as the ILcid value. The logical font resource may 
then be freed by calling the GpiDeleteSetld function. The default font for the device 
will be restored. For the display, the System Proportional font is reset: 
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GpiDeleteSetld (hPS,ILcid) 

HPS hPS Presentation space handle to delete the ILcid from. This 
must be the same handle passed to the GpiCreateLogFont 
function when the local identifier was created. 

LONG ILcid The local identifier used to refer to the font. To delete all 
logical font and bitmap identifiers, use LCID_ALL. 

Both the GpiSetCharSet and the GpiDeleteSetld return TRUE if successful and 
FALSE if an error has occurred. 

The presentation space in which the logical font resource is created is the only one in 
which that LCID is valid. A logical font resource may not be shared across multiple pre¬ 
sentations spaces, even on the same device. That resource is also invalid after the presen¬ 
tation space it was created in is released. This has the potential to cause some performance 
problems in PM applications. 

Many applications have several small windows that display program status and hint 
text to the user. In an effort to save screen space, the font used to display this information 
is often an image font smaller than the System Proportional font. Eight-point Helv font 
is frequently used because of its excellent readability. These windows might be updated 
by a notification message. When that message is received, a presentation space handle is 
retrieved; the text is output; and the handle is released. If each of those three windows 
used a micro cached presentation space—as is most common—the eight-point Helv font 
must be created for each update and set into the presentation space before outputting the 
text. After the text has been drawn, the default font should be set back into the presenta¬ 
tion space and the local identifier for the Helv font deleted. If the update of these win¬ 
dows is frequent, the overhead could slow down an application. 

Dialogs that use a font other than the system font are excellent examples of this. When 
the default System Proportional font is used in a dialog, the creation and display speed is 
excellent. When the font is changed by using the PRESPARAMS PP_FONTNAMESIZE state¬ 
ment in the dialog template, the dialog display speed is noticeably slower. This occurs 
because even though all the control windows use the same font, each one must create, 
select, and delete that font. When the default System Proportional font is used, the cre¬ 
ation is eliminated because it is the default presentation space font. 

The whole point of this is to be aware of the font creation and selection model and 
use it to your advantage. For example, if you are a Windows developer moving to Pre¬ 
sentation Manager, don’t write your code like a Windows application using the PM API. 
When a font is created and selected into a presentation space, the display performance is 
excellent even for outline fonts. Your application, however, may not see this if it spends 
all its time creating fonts rather than using them. Our fictitious application with three 
status windows has several alternatives. The default system font could be used, or the three 
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status windows could be combined into a single window. The status windows could be 
eliminated and the text drawn on a reserved portion of the client area. The main drawing 
or display area often creates a presentation space for the duration of the application. Because 
a local identifier is valid for the life of a PS, the font must be created only once and set 
when needed. 

Scaling? Shearing? and Rotating 

When an image is created and set into a presentation space, its size is defined by the size 
of glyphs for the character. Outline fonts, on the other hand, must be scaled to the de¬ 
sired size before text can be output. 

The characters of an outline are defined by a rectangle that has a width of sXDeviceRes 
and a height of sYDeviceRes. This rectangle, defined from fields in the FONTMETRIC 
structure, is referred to as the font definition space. From the font definition space, out¬ 
line fonts are scaled to a second rectangle called the character box. The character box is 
an attribute that may be set into a presentation space. The height of the font definition 
space and the height of the character box correspond to the point size of the font. There 
is no limit to the size of the character box. When the character box is set, the width and 
height of the character box correspond to the resulting lEMInc and lEMHeight metrics. 
The character box is set by the function GpiSetCharBox: 

GpiSetCharBox (hPS,pSizef) 

HPS hPS Presentation space handle in which to set the character box. 

PSIZEF pSizef Pointer to a SIZEF structure that contains the new width 

and height to set the character box to. 

The character box is used primarily to size outline fonts. Although it won’t size an 
image font, it may affect character spacing in certain character modes. We will explore 
this when character modes are discussed. 

The default baseline is defined by a line originating at point 0,0 and extending to 
point 1,0 in a Cartesian coordinate system. This baseline is considered to have 0 degrees 
of rotation. The angle of rotation may be changed by calling the GpiSetCharAngle: 

GpiSetCharAngle (hPS,pGradAngle) 

HPS hPS Presentation space handle in which to set 

baseline angle. 

PGRADIENTL pGradAngle Pointer to a GRADIENTL structure that 

defines a new end point of the angle vector 
which determines character baseline. 
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The GRADIENTL structure is comprised of two long values that define an X and Y 
point. Currently, GRADIENTL is identical to a POINTL structure. For future portability, 
however, the GRADIENTL type should be used. Because most of us think of rotation in 
terms of angle, not as ordered pairs, we must convert the desired angle into a new X and 
Y point. The desired point may be calculated by the following formula: 

X = radius * sin (angle) Y = radius * cos (angle) 

The C library functions sin and cos expect angles defined as radians. A circle has 
360 degrees, which is equivalent to 2 * PI radians. To determine the number of radians 
in a desired angle, we must multiply 2 * PI by the percent of the 360 degrees in which we 
are interested. 

AnglelnRadians = 2*3.1416* DesiredAngle / 360 

The radius is arbitrary, but should be large enough to provide an accurate point. The 
sample application has chosen 200, but your application may require a higher value. 

In addition to modifying the baseline angle, PM enables you to modify the character 
shear angle. This angle defines how individual character cells are slanted relative to the 
baseline. GpiSetCharAngle will set the new point defining the shear angle: 

GpiSetCharAngle (hPS,pPtl) 

FIPS hPS Presentation space handle in which to set shear angle. 

PPOINTL pPtl Pointer to a POINTL structure that defines a new end 
point of the angle vector that determines character shear. 

As with the baseline, the angle of character shear is specified as a point on the line 
that originates from point 0,0. The default point for character shear is 0,1, which trans¬ 
lates to 90 degrees. This point is always relative to the baseline regardless of its angle. Any 
shear angle may be specified. Extreme shear angles may cause characters to display as a 
single line. 

When text is output, characters are normally output left to right. The direction may 
be changed to one of three other values by the GpiSetCharDirection function: 

GpiSetCharDirection (hPS,IDirection) 

HPS hPS Presentation space handle in which to set character 

direction. 

LONG IDirection A flag that defines the direction characters are drawn 

relative to the baseline. It may be one of the 
following: 

CHDIRNJDEFAULT 

CHDIRNJLEFTRIGHT 
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CHDIRNTOPBOTTOM 

CHDIRN_RIGHTLEFT 

CHDIRN_BOTTOMTOP 

It appears there are four other directions that may be set; however, the CHDIRN_DEFAULT 
is initially equivalent to CHDIRN_LEFTRIGHT. The default may be changed to 
CHDIRN_TOPBOTTOM, CHDIRN_RIGHTLEFT, or CHDIRN_B0TT0MT0P using the 
GpiSetDef Attrs function. The CHDIRN_RIGHTLEFT flag will cause characters to be par¬ 
allel to the baseline, but the current position is advanced to the left after each character is 
drawn. Both CHDIRN_T0PBOTTOM and CHDIR_BOTTOMTOP flags will cause the characters 
to be drawn in columns 90 degrees to the baseline. CHDIRN_T0PB0TT0M rotates the char¬ 
acter box 90 degrees clockwise and CHDIR_B0TT0MT0P 90 degrees counterclockwise. 

Character Modes 

A presentation space has three modes that control how characters use the current setting 
of the character attributes for angle, box, and shear. Outline fonts always use the current 
setting for angle, box, and shear and are never affected by character mode settings. Image 
fonts may be affected only by rotation and character box; the characters are never sheared. 
The current character mode may be set by calling the GpiSetCharMode function: 

GpiSetCharMode (hPS,IMode) 

HPS hPS Presentation space handle in which to set the character box. 

LONG IMode The new character mode to set. It may be one of the 

following: 

CMJDEFAULT 

CM_MODEl 

CM_MODE2 

CM_MODE3 

The CM_DEFAULT mode is initially equivalent to CM_M0DE1, but may be changed to 
CM_M0DE2 or CM_M0DE3 by the GpiSetDef Attrs function. CM_M0DE1 allows the selec¬ 
tion of a raster or outline font into the presentation space. Image fonts are positioned 
based on their metrics, and character box values are ignored. In CM_M0DE2, the first 
character is positioned as in CM_M0DE1, but the second and subsequent characters are 
positioned based on the width of the character box. The actual character glyphs are not 
stretched, but spacing between characters is increased. The vertical position of the char¬ 
acters is not affected. In CM_M0DE2, characters also are rotated based on the current 
character angle. The glyphs, however, always maintain a perpendicular orientation to 
the default (1,0) baseline. The result is a stair-step effect when image fonts are rotated in 
CM_M0DE2. The last mode, CM_M0DE3, does not allow image fonts to be set into a presen¬ 
tation space. 
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Rotation and Shear in PMFONT 

To enable you to see how character modes, rotation, shear, and character box affect im¬ 
age and outline characters, a special panel has been added to PMFONT. This panel is 
displayed when the Rotation/Shear menu item is selected from the Display pop-up menu. 

A sample text string in the currently selected font is displayed centered on the right 
side of the client window with a rectangle drawn around it. The rectangle is calculated by 
using the GpiQueryT extBox function. The rectangle defines the bounds of the text string. 
On the shear panel are entry fields that control the width and height of the character 
box. The default size is 50x50 but you may change the size to any value. The character 
shear may be changed by entering a new X and Y point that defines a new end point for 
the baseline. A new baseline angle may also be specified by scrolling the spin control or 
by directly entering a value between 0 and 360. Notice that in character mode one 
(CM_M0DE1), image fonts rotate around the logical 0,0 point, but the baseline remains 
unchanged. If you change the character mode to CM_M0DE2, the characters are oriented 
along the modified baseline. The characters, however, remain perpendicular to the de¬ 
fault baseline. You also will notice that the spacing between characters is wider. This occurs 
because the character box width affects the spacing of image fonts in CM_M0DE2. The 
character shear may also be modified, but will affect only outline fonts. As with the baseline 
angle, you may supply a new X and Y point or dial in a new shear angle. The default 
shear is 90 degrees, which results in character boxes that are perpendicular to the baseline 
regardless of its angle. Angles less than 90 degrees cause the characters to slant to the 
right, and angles greater than 90 degrees will cause a slant to the left. Finally, a text entry 
field exists to enable you to enter your own text string to display. 

Character Bundle Structure 

This chapter has discussed many functions that modify character attributes. Almost all 
these functions are actually modifying the current character bundle in the presentation 
space. The character bundle, or CHARBUNDLE, is comprised of fields that control charac¬ 
ter shear, rotation, size, color, and so on (see Table 7.2). The CHARBUNDLE is modified by 
calling the GpiSetAttrs function. The GpiSetAttrs function can set attributes in all 
bundle types, but we are only concerned with the character bundle. 

GpiSetAttrs (hPS,IPrimitiveType,ulAttrMask,ulDefaultMask,pBundle) 

HPS hPS Presentation space handle in which to modify the 

character bundle. 

LONG IPrimitiveType Identifies the bundle being set, PRIM_CHAR. 
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ULONG ulAttrMask A ULONG containing one or more flags that 

identify fields in the CHARBUNDLE which are 
to be set. It may be one or more of the following: 

CBB_COLOR 

CBB_BACKCOLOR 

CBB_MIX_MODE 

CBB_BACK_MIX_MODE 

CBB_SET 

CBB_MODE 

CBB_BOX 

CBB_ANGLE 

CBB_SHEAR 

CBB_DIRECTION 


ULONG ulDefaultMask A ulong containing one or more flags that when 

set along with the same flag in the ulAttrMask 
field will cause the default value for that attribute 
to be set. 

PBUNDLE pBundle Pointer to a bundle structure of IPrimitive type. 

You will find in the process_paint function of PMFONT that character attributes 
for the metrics panel are set through the individual functions, and the shear panel sets 
them by using the CHARBUNDLE. Whenever possible, multiple attributes should be set by 
using the GpiSetAtt rs function. For example, assuming the fields of the character bundle 
have been initialized, the following code clips accomplish the same task: 


GpiSetCharSet 

GpiSetCharAngle 

GpiSetCharShear 

GpiSetCharBox 


(hPS 3 CurrentCB.usSet); 
(hPS 5 &CurrentCB.ptlAngle); 
(hPS,&CurrentCB.ptlShear); 
(hPSj&CurrentCB.sizfxCell); 


GpiSetAttrs(hPS,PRIM_CHAR,CBB_SET | CBB_ANGLE | CBB_SHEAR J 
CBB_BOX,0,&CurrentCB); 

When resetting the default values by using the GpiSetAtt rs function, you must set 
the CBB_ flag for the field to reset in both the ulAttrMask and ulDef ault values. The 
contents of that field are ignored and need not be initialized. Resist the temptation to 
attempt to reset a default value in the following way; it will not work: 

CHARBUNDLE cb; 


cb.usSet = LCID_DEFAULT; 

GpiSetAttrs (hPS,PRIM_CHAR,CBB_SET,0,(PBUNDLE)&cb); 

The current setting of the CHARBUNDLE may be retrieved by the GpiQueryAttrs 
function. 
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Table 7.2. Character functions and equivalent CHARBUNDLE fields and flags. 


GPI Function 

CHARBUNDLE Field 

CHARBUNDLE Flag 

GpiSetCharSet() 

usSet 

CBB_SET 

GpiSetCharBox() 

sizfxCell 

CBB_BOX 

GpiSetCharShear() 

pltShear 

CBB_SHEAR 

GpiSetCharMode() 

usPrecision 

CBB_MODE 

GpiSetCharDirection() 

usDirection 

CBB_DIRECTION 

GpiSetCharExtra() 

fxExtra 

CBB_EXTRA 

GpiSetCharBreakExtra() 

fxBreakExtra 

cbb_break_extra 

GpiSetT extAlignment() 

usTextAlign 

CBB_TEXT_ALIGN 


Logical Inches 

To make fonts more legible on the display device, many applications display text accord¬ 
ing to a logical inch rather than a physical inch. A logical inch is typically 35 percent to 
40 percent larger than an actual inch. 

Code Pages 

A code page was described as mapping a code point to character glyph. That might be all 
you would need to know if your application existed within a vacuum, but it does not. 
Code pages control how your application interacts with the system and other applica¬ 
tions. For example, if your application uses keyboard input, the message queue code page 
will determine how characters are translated from the keyboard. You may change the 
default by calling the WinSetCp function. If the code page used when a font was created 
is not the same as the message queue code page, some characters might not display cor¬ 
rectly. This occurs because the keystroke’s translation is based on the message queue code 
page and is performed before your application receives the message. The code pages avail¬ 
able on the system may be retrieved by calling the WinQueryCpList function. It will 
return an array of code page IDs. 

In addition to the message queue code page, each presentation space has a code page 
that may be set or queried. It defines what code page is used by the default font. It has no 
effect on fonts that are created and set into the presentation space. The PMFONT appli¬ 
cation enables you to change the code page that is used to create the font. Values may be 
selected from the code page menu. 
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While developing an application, various keyboard templates should be installed and 
tested on the system in conjunction with testing your application. The keyboard layout 
may be changed using the KEYB program. This is a utility that comes with OS/2. It 
will change the keyboard layout for all DOS and OS/2 sessions. Applications receive no 
notification of the change. KEYB takes a two-character abbreviation for the keyboard 
template to set as the current template. For example, GR will set the German key¬ 
board template. 

To aid in converting strings and characters from one code page to another, PM sup¬ 
plies two conversion functions, WinCpTranslateChar andWinCpTranslateString. Each 
requires an anchor block handle and a source and destination code page. 

The PMFONT Application 

The following files are necessary to build the PMFONT application: 

PMFONT.C 

PMFONT.DEF 

PMFONT.DLG 

PMFONT.H 

PMFONT.ICO 

PMFONT.RC 

ABOUT.DLG 

SLIDE.DLG 

PMFONT.C 

/* 

PM Font Program 
Chapter 7 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 
. */ 


#define INCL_DOS 
#define INCL_WIN 
#define INCL_GPI 
#define INCL_GPILCIDS 
#define INCL_DEV 
#define INCL_WINERRORS 

#include <stdio.h> 
#include <string.h> 
#include <math.h> 
#include <stdlib.h> 
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#include <os2.h> 

#include "pmfont.h" 

#include "chap7.h" 

#include "..\common\about.h" 

BOOL APIENTRY GpiSetTextAlignment(HPS,LONG,LONG); 

HAB hab; 

PVOID pMem; 

char szBuff1[MAX_BUFF]; 

int cxOhar = 0; 
int cyGhar = 0; 

HWND hWndMetrics = 0; 

HWND hWndShear = 0; 

HWND hMenu; 

USHORT usDisplayMode = IDMJVIETRICS; 

USHORT usCharMode = IDM_CHMODE_ONE; 

USHORT usSelection = 0; 

USHORT usOurrentCP = 850; 

USHORT usCurrentFontlndex = 0; 

LONG cxFontRes; 

LONG cyFontRes; 

LONG lHorzRes; 

LONG IVertRes; 
double dRctSine; 
double dRotCosine; 

CHAR szFontFace[] = "10.Helv"; 

CHAR szDisplayStr[MAX_BUFF]; 

CHAR szSpecialStr[MAX_STR]; 

CHAR szUserStr [MAX__BUFF] ; 

CHARBUNDLE CurrentCB; 

GRADIENTL DefaultAngle = {0L,0L}; 

SIZEF DefaultCharBox = {0,0}; 

FIXED CharExtra = 0; 

FIXED BreakExtra = 0; 

CHAR *szWeights[] = 

{ 

"Ultra-light", 

"Extra-light", 

"Light 1 , 

"Semi-light", 

"Medium", 

"Semi-bols", 

"Bold", 

"Extra-bols", 

"Ultra-bold" 

}; 
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CHAR *szWidths[] = 

{ 

"Ultra-condensed" , 
"Extra-condensed", 
"Condensed", 
"Semi-condensed", 
"Medium", 
"Semi-expanded", 
"Expanded", 
"Extra-expanded", 
"Ultra-expanded" 

}; 


CHAR *szQuality[]= 

{ 

"Undefined", 

"DP Quality", 

"DP Draft", 

"Near Letter Quality", 
"Letter Quality" 

}; 

CHAR *szFormat[]= 

{ 

"Device", 

"GP1" 

}; 


CHAR *szType[]= 

{ 

" Bitmap", 

" Outline" 

}; 


CHAR *szSelection[]= 
{ 

"Bold", 

" Italic", 

" Strikeout", 

" Underscore", 

" Outline" 

}; 


CHAR *szSpacing[] = 

{ 

"Proportional", 
"Fixed" 

}; 
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int iCharModes[] = 

{ 

CMJ/I0QE1 , CM_M0DE2, CM_M0DE3 

}; 


#define B(JFF_SIZE 80 

HDC hDisplaylnfoDC = 0; 

HPS hDisplayPS = 0; 

HWND hWndFrame,hWndClient; 

HWND hWndDC; 

HWND hFontLBox; 

PFONTMETRICS pScreenFontMetrics = 0; 


MRESULT APIENTRY ClientWndProc(HWND,ULONG,MPARAM,MPARAM); 
MRESULT APIENTRY MetricsWndProc(HWND,ULONG,MPARAM,MPARAM); 
MRESULT APIENTRY ShearWndProc(HWND,ULONG,MPARAM,MPARAM); 


int main () 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG fIFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | 

FCF_SIZEBORDER | FCF_MINMAX ] 
FCF_SHELLPOSITION | FCF_TASKLIST | 
FCF_ICON | FCFJ/IENU; 

CHAR szClientClass[] = "CLIENT"; 

RECTL Recti; 
int i = 0; 
int iClientHeight; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgOueue (hab, 0); 

DosAllocMem((PPVOID)&pMem,0x1000,PAG_READ j PAG_WRITE); 
DosSubSet(pMem,DOSSUB_INIT | DOSSUB_SPARSE_OBJ,8192); 

WinRegisterClass (hab,szClientClass,ClientWndProc,CS_SIZEREDRAW 
CS_CLIPCHILDREN, 0); 

WinLoadString (hab,0,IDS_APPNAME,sizeof(szBuffl),szBuff1); 

WinGueryWindowRect (HWNDJDESKTOP,&Rectl); 
iClientHeight = WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - 
WinGuerySysValue(HWND_DESKTOP,SV_CYIC0N); 
hWndFrame = WinCreateStdWindow (HWND_DESKTOP,0,&fIFrameFlags, 
szClientClass, szBuffl,0,0,ID_APPNAME,&hWndClient); 

WinSetWindowPos (hWndFrame,HWND_T0P,0, 

WinOuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - iClientHeight, 
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WinQuerySysValue(HWND_DESKTOP,SV_CXSCREEN),iClientHeight, 
SWP_SHOW | SWP_ACTIVATE J SWP_ZORDER | SWP_SIZE | SWP_M0VE); 

hMenu = WinWindowFromID (hWndFrame,FID_MENU); 
hWndDC = WinOpenWindowDC(hWndClient); 

WinEnableWindowUpdate(hWndClient,FALSE); 
if (create_controls(hWndClient)) 

{ 

WinEnableWindowUpdate(hWndClient,TRUE); 

WinShowWindow (hFontLBox,TRUE); 

WinSendMsg(hFontLBox,LM_SELECTITEM 3 MPFROMSHORT(0), 

MPFROMSHORT(TRUE)); 

WinSetFocus(HWND_DESKTOP,hFontLBox); 

WinShowWindow (hWndMetrics,TRUE); 

} 

else 

return(0); 

while (WinGetMsg (hab 3 &qmsg 3 0 3 0 3 0)) 

WinDispatchMsg (hab 3 &qmsg); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return 0; 

} 


VOID APIENTRY charbox_from_pointsize (FIXED fxPtSize,PSIZEF pSizef) 

{ 

pSizef->cx = MAKEFIXED( ((fxPtSize * cxFontRes) / 72),0); 
pSizef->cy = MAKEFIXED( ((fxPtSize * cyFontRes) / 72) 3 0); 

} 


void APIENTRY cleanup() 

/*.*\ 


This function is called to free the memory allocated and destroy 
the application window. 


\*.-.-.*/ 

{ 

if (pScreenFontMetrics) 

DosFreeMem(pScreenFontMetrics); 

DosFreeMem(pMem); 
if (hWndMetrics) 

WinDestroyWindow (hWndMetrics); 
if (hWndShear) 

WinDestroyWindow (hWndShear); 
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WinDestroyWindow (hWndFrame); 

} 


void APIENTRY draw_grid(HPS hPS,PRECTL pRectl) 

{ 

POINTL ptlGrid[4]; 

ptlGrid[0].x = pRectl->xLeft; 
ptlGrid[0].y = pRectl->yTop / 2; 
ptlGrid[1].x = pRectl->xRight; 
ptlGrid[1].y = ptlGrid[0].y; 
ptlGrid[2].x = pRectl->xLeft + 

((pRectl->xRight - pRectl->xLeft) / 2); 
ptlGrid[2].y = pRectl->yBottom; 
ptlGrid[3].x = ptlGrid[2].x; 
ptlGrid[3].y = pRectl->yTop; 

GpiMove (hPS,&ptlGrid[0]); 

GpiLine (hPS,&ptlGrid[1]); 

GpiMove (hPS,&ptlGrid[2]); 

GpiLine (hPS,&ptlGrid[3]); 


BOOL APIENTRY create_controls(HWND hWndClient) 

/*..*\ 


This function will create the font selection list box and load 
the metrics and rotation dialogs. The fonts will be added to the 
list box and the default display strings are loaded. All windows 
are left hidden. 


\*.*/ 

{ 

RECTL ClientRectl; 

RECTL MetricsRectl; 

HWND hWndEdit; 

HPS hPS; 

WinLoadString (hab, 0, IDS_DISPLAY_TEXT,MAX_BUFF,szDisplayStr); 
WinLoadString (hab, 0, IDS_SPECIAL_TEXT 3 MAX_STR 3 szSpecialStr); 

WinQueryWindowRect(hWndClient,(PRECTL)&ClientRectl); 

/* Load the Metrics Window */ 

if (hWndMetrics = WinLoadDlg(hWndClient 3 hWndClient,MetricsWndProc 3 
0 3 METRICS_DLG 3 0)) 

{ 

WinQueryWindowRect(hWndMetrics,(PRECTL)&MetricsRectl); 
WinSetWindowPos (hWndMetrics,HWND_T0P 3 
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cxChar,ClientRectl.yTop - MetricsRectl.yTop - (cyChar * 5),0,0, 
SWP_ZORDER | SWP_M0VE); 

} 

else 

return(FALSE); 

/* Create the font selection list box */ 

if (hFontLBox = WinCreateWindow (hWndClient,WC_LISTBOX,0, 

0L, 

cxChar,ClientRectl.yTop - (cyChar * 4), 

MetricsRectl.xRight,cyChar * 3, 
hWndClient,HWNDJTOP,F0NT_LB0X,0,0)) 

{ 

WinSetPresParam(hFontLBox,PP_FONTNAMESIZE,strlen(szFontFace)+1, 
(PVOID)szFontFace); 
hPS = WinGetPS (hWndClient); 

pScreenFontMetrics = init_font_LBox(hFontLBox,hPS); 
WinReleasePS(hPS); 

} 

else 

return(FALSE); 

/* Load the Shear Window and leave it hidden */ 
if (hWndShear = WinLoadDlg(hWndClient,hWndClient,ShearWndProc, 
0,SHEAR_DLG,0))] 

{ 

WinQueryWindowRect(hWndShear,(PRECTL)&MetricsRectl); 
WinSetWindowPos (hWndShear,HWNDJTOP, 

cxChar,ClientRectl.yTop - MetricsRectl.yTop - (cyChar * 5), 
0,0, 

SWP_ZORDER j SWP_MOVE); 

WinLoadString (hab,0,IDS_USER_TEXT,MAX_STR,szUserStr); 
hWndEdit = WinWindowFromID(hWndShear,DIDJJSERJTEXT); 

WinSendMsg(hWndEdit,EM_SETTEXTLIMIT,MPFROMSHORT(MAXJ3TR),0); 
WinSetWindowText(hWndEdit,szUserStr); 

} 

else 

return(FALSE); 
return (TRUE); 


USHORT APIENTRY post_error(HWND hWnd,USHORT usErrorlD) 

/*.-.*\ 


This is a utility function that will post a message box with 
a string loaded from the resource file. 


\* 


*/ 
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{ 

WinLoadString (hab,0,usErrorID,MAX_BUFF,szBuff1); 
return ((USHORT)WinMessageBox(HWND_DESKTOP,hWnd,(PSZ)szBuffl, 
(PSZ)"Error",0,MB_OK | MB_ICONHAND | MB_APPLMODAL)); 

} 


void APIENTRY process_command(HWND hWnd,MPARAM mpl.MPARAM mp2) 

/* . . *\ 


All WM_COMMAND messages received by the client window will be 
processed here. 


\*. - . - . */ 

{ 

USHORT usAction; 

USHORT usAttribute; 

switch(SHORT1FROMMP(mp1)) 

{ 

case IDMJ/IETRICS: 

if (usDisplayMode != IDM_METRICS) 

{ 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_ROTATION,TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_METRICS,TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 

WinShowWindow(hWndMetrics,TRUE); 

WinShowWindow(hWndShear,FALSE); 

usDisplayMode = IDM_METRICS; 

/* Force a new font to be created */ 

WinSendMsg(hWndClient,WM_CONTROL, 

MPFR0M2SH0RT(F0NT_LB0X,LN_SELECT),0); 

WinlnvalidateRect(hWndClient,0,FALSE); 

} 

break; 

case IDM_ROTATION: 

if (usDisplayMode != IDM_ROTATION)) 

{ 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_METRICS,TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_ROTATION,TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 

WinShowWindow(hWndShear,TRUE); 
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WinShowWindow(hWndMetrics,FALSE); 

usDisplayMode = IDM_ROTATION; 

WinlnvalidateRect(hWndClient,0,FALSE); 

} 

break; 

case IDM_CHMODE_ONE: 
case IDM_CHMODE_TWO: 
case IDM_CHMODE_THREE: 

WinSendMsg (hMenu,MM_SETITEMATTR, 
MPFR0M2SH0RT(usCharMode,TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 
WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(MPFROMSHORT(mpl),TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 
usCharMode = SHORT1FROMMP(mp1); 

/* Force a new font to be created */ 
WinSendMsg(hWndClient,WM_CONTROL, 

MPFR0M2SH0RT(FONT_LBOX,LN_SELECT),0); 
break; 

case IDM_ATTR_ITALIC: 
case IDM_ATTR_BOLD: 
case XDM_ATTR_UNDERSCORE: 
case IDM_ATTR_STRIKEOUT: 
case IDM_ATTR_OUTLINE: 

switch (SH0RT1FROMMP(mpl)) 

{ 

case IDM_ATTR_ITALIC: 

usAttribute = FATTR_SEL_ITALIC; 
break; 

case IDM_ATTR_BOLD: 

usAttribute = FATTR_SEL_BOLD; 
break; 

case IDM_ATTR_UNDERSCORE: 

usAttribute = FATTR_SEL_UNDERSCORE; 
break; 

case IDM_ATTR_STRIKEOUT: 

usAttribute = FATTR_SEL_STRIKEOUT; 
break; 

case IDM_ATTR_OUTLINE: 

usAttribute = FATTR_SEL_OUTLINE; 
break; 

} 

if (usSelection & usAttribute) 

{ 

usSelection &= -usAttribute; 

usAction = 0; 


} 
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{ 

usSelection |= usAttribute; 
usAction = MIA_CHECKED; 

} 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(SHORT1FROMMP(mpl),TRUE), 
MPFR0M2SH0RT(MIA_CHECKED J usAction)); 

/* Force a new font to be created*/ 

WinSendMsg(hWndClient,WM_C0NTR0L, 

MPFR0M2SH0RT(F0NT_LB0X,LN_SELECT),0); 
break; 

case IDM_CP437: 
case IDM_CP850: 
case IDM_CP852: 
case IDM_CP857: 
case IDM_CP860: 
case IDM_CP861: 
case IDM_CP863: 
case IDM_CP865: 
case IDM_CP1004: 
case IDM_CP037: 
case IDM_CP273: 
case IDM_CP274: 
case IDM_CP277: 
case IDM_CP278: 
case IDM_CP280: 
case IDM_CP282: 
case IDM_CP284: 
case IDM_CP285: 

if (usCurrentCP != SH0RT1FROMMP(mpl)) 

{ 

WinSendMsg (hMenu,MM_SETITEMATTR 3 
MPFR0M2SH0RT(usCurrentCP,TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,FALSE)); 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(SHORT1FROMMP(mpl),TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED)); 
usCurrentCP = SH0RT1FROMMP(mpl); 

/* Force a new font to be created */ 

WinSendMsg(hWndClient,WM_C0NTR0L, 

MPFR0M2SH0RT(F0NT_LB0Xj LN_SELECT),0); 

} 

break; 

case IDM_AB0UT: 

WinLoadString (hab, 0, IDS_APPNAME, sizeof(szBuff1), szBuffl); 

DisplayAbout (hWnd, szBuff1); 

break; 
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void APIENTRY process_control(HWND hWnd.HPS hPS,MPARAM mpl.MPARAM mp2) 
/* 

All WM_C0NTR0L messages received by the client window will be 
processed here. 


{ 


if (LOUSHORT(mpl) == FONT_LBOX) 

{ 

if (SH0RT2FR0MMP(mp1) == LN_SELECT) 

{ 

usCurrentFontIndex = (LONG)WinSendMsg (hFontLBox, 
LM_QUERYSELECTION,MPFROMSHORT(LIT_FIRST),0); 

WinSendMsg(hWndMetrics,WM_UPDATE_METRICS,0, 
pScreenFontMetrics + usCurrentFontlndex); 
create_font (hPS,(int)usCurrentFontlndex,pScreenFontMetrics); 
WinlnvalidateRect (hWndClient,0,FALSE); 

} 

} 


void APIENTRY process_paint (HWND hWnd.HPS hPS) 


The entire client area is erased and the right side is redrawn 
based on the current display mode. If the mode is IDM_METRICS, 
two strings are displayed in the current font. If the mode is 
IDM_ROTATION : a string is drawn using the current rotation and 
shear angles set in the current CFIARBUNDLE. 


int 

i; 

HRGN 

hClipRgn; 

HRGN 

hPrevRgn; 

RECTL 

Recti; 

RECTL 

ClientRectl; 

RECTL 

PanelRectl; 

POINTL 

Pointl; 

POINTL 

TempPoint; 

POINTL 

Ptl[TXTBOX_COUNT + 1] 

double 

dSine; 

double 

dCosine; 
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int iLength; 

int xExtent; 

hPS = WinBeginPaint(hWnd,hPS,&Rectl); 

/* Redraw the background of the Window */ 

WinQueryWindowRect (hWnd,(PRECTL)&ClientRectl); 

WinQueryWindowRect (hWndMetrics,(PRECTL)&PanelRectl); 

PanelRectl.yTop = ClientRectl.yTop; 

PanelRectl.xRight += cxChar * 2; 

WinFillRect(hPS,(PRECTL)&PanelRectl,CLR_PALEGRAY); 

ClientRectl.xLeft = PanelRectl.xRight; 

WinFillRect(hPS,(PRECTL)&ClientRect1,CLR_WHITE); 

/* Set up a clipping rectangle before drawing the text */ 
hClipRgn = GpiCreateRegion(hPS,1,&ClientRectl); 

GpiSetClipRegion(hPS,hClipRgn,&hPrevRgn); 

/* Update the character mode */ 

GpiSetCharMode (hPS,iCharModes[(usCharMode - IDM_CHMODE) - 1]); 

if (usDisplayMode == IDM_METRICS) 

{ 

GpiSetCharAngle (hPS,&DefaultAngle); 

GpiSetCharSet (hPS,DISPLAY_FONT); 

Pointl.x = PanelRectl.xRight + cxChar; 

Pointl.y = (ClientRectl.yTop / 3) * 2; 

GpiCharStringAt (hPS,&Pointl,strlen(szDisplayStr), 
(PSZ)szDisplayStr); 

Pointl.y = ClientRectl.yTop / 3; 

GpiCharStringAt (hPS,&Pointl,strlen(szSpecialStr), 

(PSZ)szSpecialStr); 

} 

else if(usDisplayMode == IDM_ROTATION) 

{ 

draw_grid(hPS,(PRECTL)&ClientRectl); 

GpiSetCharExtra(hPSjCharExtra); 

GpiSetCharBreakExtra(hPS,BreakExtra); 

iLength = strlen(szUserStr); 

/* Set the character set and box but reset the angle of rotation*/ 
GpiSetAttrs(hPS,PRIM_CHAR,CBB_SET | CBB_B0X | CBB_ANGLE, 
CBB_ANGLEj&CurrentCB); 

/* Query the extent of the string before rotation or shearing */ 
GpiQueryTextBox(hPS,iLength,(PCH)szUserStr,TXTBOX_COUNT,Ptl); 
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Pointl.x = PanelRectl.xRight + 

((ClientRectl.xRight - ClientRectl.xLeft) / 2); 

Pointl.y = ClientRectl.yTop / 2; 

if (Ptl[TXTBOX_BOTTOMLEFT].x < Ptl[TXTBOX_TOPRIGHT].x) 

xExtent=(Ptl[TXTBOX_BOTTOMLEFT].x - Ptl[TXTBOX_TOPRIGHT].x / 2); 
6lS6 

xExtent=(Ptl[TXTBOX_TOPRIGHT].x - Ptl[TXTBOX_BOTTOMLEFT].x / 2); 

/* Calculate the starting point for the rotated string */ 
dSine = xExtent * dRotSine; 
dCosine = xExtent * dRotCosine; 

Pointl.x += ((LONG)dCosine * lHorzRes)/(LONG)IVertRes; 

Pointl.y += (LONG) dSine; 

/* Set the character angle and shear */ 

GpiSetAttrs(hPS,PRIM_CHAR,CBB_ANGLE | CBB_SHEAR,0,&CurrentCB); 

/* Get the extents of the string with rotation and shearing */ 
GpiQueryTextBox(hPS,iLength,(PCH)szUserStr,TXTBOX_COUNT,Ptl); 

for (i = 0; i < 5; i++) 

{ 

Ptl[i]-x += Pointl.x; 

Ptl[i].y += Pointl.y; 

} 

TempPoint = Ptl[2]; 

Ptl[2] = Ptl[3]; 

Ptl[3] = TempPoint; 

Ptl[4].x = Ptl[0].x; 

Ptl[4].y = Ptl[0].y; 

/* Draw a polygon which displays the text bounding box */ 

GpiMove(hPS,(PPOINTL)&Ptl[TXTBOX_TOPLEFT]); 
GpiPolyLine(hPS,5L,Ptl); 

GpiCharStringPosAt (hPS,&Pointl,0L,CHS_LEAVEPOS, 
iLength,(PSZ)szUserStr,0); 

} 

GpiSetClipRegion(hPS,0,&hPrevRgn); 

WinEndPaint (hPS); 


PFONTMETRICS APIENTRY init_font_LBox (HWND hLBox,HPS hPS) 


This function will query metrics for supplied presentation space 
and then enumerate its public and private fonts. 
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HDC hDC; 

PSZ pFace; 

ULONG ulSize = 0; 

ULONG ulCount = 0; 

int i; 

PVOID pData; 

PFONTMETRICS pFontMetrics; 

HATOMTBL hAtomTable = WinQuerySystemAtomTable(); 

hDC = GpiQueryDevice(hPS); 

DevQueryCaps (hDC,CAPS_HORIZONTAL_RESOLUTION,1L,(PLONG)&lHorzRes); 
DevQueryCaps (hDC,CAPS_VERTICAL_RESOLUTION, 1L, (PLONG)&lVertRes); 
DevQueryCaps (hDC,CAPS_HORIZONTAL_FONT_RES 5 1,&cxFontRes); 
DevQueryCaps (hDC,CAPS_VERTICAL_FONT_RES,1,&cyFontRes); 

ulCount = GpiQueryFonts (hPS,QF_PUBLIC J QF_PRIVATE,0, 

&ulCount,(LONG)sizeof(FONTMETRICS),0); 

if (ulCount) 

{ 

DosAllocMem ((PPVOID)&pFontMetrics, 

sizeof(FONTMETRICS) * (USHORT)ulCount, 

OBJ_TILE | PAG_READ j PAG_WRITE j PAG_COMMIT); 

GpiQueryFonts (hPS,QF_PUBLIC | QF_PRIVATE,0, 

&ulCount,(LONG)sizeof(FONTMETRICS),pFontMetrics); 

WinSendMsg (hLBox,LM_DELETEALL,0,0); 

for (i =0; i < (int)ulCount; i++) 

{ 

#ifdef T00LKT21 

/* If the facename has been truncated, query the atom text */ 
if ( ((pFontMetrics+i)->fsType & FM_TYPE_FACETRUNC) && 

(ulSize = WinQueryAtomLength(hAtomTable, 

(pFontMetrics+i)->FaceNameAtom)) ) 

{ 

ulSize++; 

DosSubAlloc(pMem,(PPVOID)&pData,ulSize); 
if (WinQueryAtomName (hAtomTable, 

(pFontMetrics+i)->FaceNameAtom,pData,ulSize)) 
pFace = pData; 
else 

pFace = (pFontMetrics+i)->szFacename; 

} 

else 

#endif 

pFace = (pFontMetrics+i)->szFacename; 

WinSendMsg (hLBox,LM_INSERTITEM,(MPARAM)LIT_END,(MPARAM)pFace) 
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if (ulSize) 

DosSubFree(pMem,pData,ulSize); 

} 

} 

return (pFontMetrics); 


BOOL APIENTRY create_font(HPS hPS,int i,PFONTMETRICS pFontArray) 

/*.-.*\ 


This function will create a new font based on the current selec¬ 
tion in the font list box and style and code page attributes set 
via the menu. The PS is first reset to the default character set 
attribute and character. 


\*. 

{ 

FATTRS fattr; 
SIZEF sizef; 


/* Reset the character box to the default size */ 
sizef.cx = MAKEFIXED((pFontArray+i)->lEmInc,0); 
sizef.cy = MAKEFIXED((pFontArray+i)->lEmHeight,0); 
GpiSetCharBox (hPS,&sizef); 

GpiSetCharSet (hPS,LCID_DEFAULT); 

GpiDeleteSetld (hPS,DISPLAY_FONT); 


strcpy(fattr.szFacename, 
fattr.usRecordLength = 
fattr.fsSelection 
fattr.IMatch 
fattr.idRegistry 
fattr.usCodePage 
fattr.IMaxBaselineExt = 
fattr.lAveCharWidth 
fattr.fsType 
fattr.fsFontUse 
return (GpiCreateLogFont 


(PSZ)((pFontArray+i)->szFacename); 

sizeof(FATTRS); 

usSelection; 

(pFontArray+i)->lMatch; 
(pFontArray+i)->idRegistry; 
usCurrentCP; 

(pFontArray+i)->lMaxBaselineExt; 

(pFontArray+i)->lAveCharWidth; 

0 ; 

0 ; 

hPSj 0,DISPLAY_FONT,&fattr)); 


*/ 


void APIENTRY size_controls(MPARAM INewSize) 

/* .. .*\ 


This function will reposition the font selection list box and 
the metrics and shear panel windows based on the new client 
window size. 


\* 


*/ 
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{ 

SHORT sNewWidth = SHORT1FROMMP(INewSize); 

SHORT sNewHeight = SH0RT2FR0MMP(INewSize); 

RECTL MetricsRectl; 

WinQueryWindowRect(hWndMetrics,(PRECTL)&MetricsRectl); 

WinSetWindowPos (hWndMetrics,HWND_TOP, 

cxChar,sNewHeight - MetricsRectl.yTop - (cyChar * 5),0,0, 
SWP_MOVE); 

WinQueryWindowRect(hWndShear,(PRECTL)&MetricsRectl); 

WinSetWindowPos (hWndShear,HWND_T0P, 

cxChar,sNewHeight - MetricsRectl.yTop - (cyChar * 5),0,0, 
SWP_M0VE); 

WinSetWindowPos (hFontLBox,HWND_T0P, 

cxChar,sNewHeight - (cyChar * 4),0,0,SWP_ZORDER | SWPJ/IOVE); 

} 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

/* - - -.*\ 


This is the application callback that handles the messages 
necessary to maintain the client window. 


\*.*/ 

{ 

MRESULT mReturn = 0; 

BOOL bHandled = TRUE; 

FONTMETRICS FontMetrics; 
static HPS hPS; 

SIZEL sizel; 


switch(msg) 

{ 

case WM_CREATE: 

/* Create a PS for the window */ 
sizel.cx = sizel.cy = 0; 

hPS = GpiCreatePS(hab,WinOpenWindowDC(hWnd),(PSIZEL)&sizel, 
PU_PELS | GPIF_DEFAULT j GPIT_MICRO | GPIA_ASSOC); 

/* Query the height of the default font. */ 
GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 

(PFONTMETRICS)&FontMetrics); 
cyChar = FontMetrics.IMaxBaselineExt; 
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cxChar = FontMetrics.lAveCharWidth; 

bHandled = FALSE; 

break; 

case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl),PVOIDFROMMP(mp2),CLR_WHITE); 

mReturn = MRFROMLONG(0L); 

break; 

case WM_SIZE: 

size_controls(mp2); 
break; 

case WM_COMMAND: 

process_command(hWnd,mp1 3 mp2); 
break; 

case WM_C0NTR0L: 

process_control (hWnd,hPS,mp1,mp2); 
break; 

case WM_PAINT: 

process_paint (hWnd,hPS); 
break; 

case WM_DESTROY: 
cleanup(); 
break; 

default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 

} 


MRESULT EXPENTRY MetricsWndProc (HWND hWnd, ULONG msg 

MPARAM mp2) 


/* 


MPARAM mpl, 


*\ 


This dialog panel displays the metrics of the currently selected 
font. When the private WM_UPDATE_METRICS message is received, the 
text of the child windows is updated with the contents of the 
fontmetrics pointed to by mp2. 


\* 
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MRESULT mReturn = 0; 

BOOL bHandled = TRUE; 

PFONTMETRICS pFM; 

CHAR szTemp[80]; 

switch(msg) 

{ 

case WM_UPDATE_METRICS: 
pFM = (PFONTMETRICS)mp2; 

WinSetWindowText(WinWindowFromID(hWnd,DID_FAMILYNAME), 
pFM->szFamilyname); 

WinSetWindowT ext(WinWindowF romID(hWnd,DID_FACENAME), 
pFM->szFacename); 

ltoa(pFM->lLowerCaseAscent,(PSZ)szTemp, 10 ) ; 

WinSetWindowText(WinWindowFromID(hWnd,DID_LOWERCASEASCENT), 
(PSZ)szTemp); 

ltoa(pFM->lXHeight,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_XHEIGHT), 

(PSZ)szTemp); 

ltoa(pFM->lMaxAscender,(PSZ)szTemp, 10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_MAXASCENDER), 

(PSZ)szTemp); 

ltoa(pFM->HVIaxDescender, (PSZ)szTemp, 10); 

WinSetWindowT ext(WinWindowF romID(hWnd,DID_MAXDECENDER), 
(PSZ)szTemp); 

ltoa(pFM->lLowerCaseDescent,(PSZ)szTemp, 10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_LOWERCASEDECENT), 
(PSZ)szTemp); 

ltoa(pFM->lEmInc,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_EMINC),(PSZ)szTemp); 

ltoa(pFM->1InternalLeading,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_INTERNALLEADING), 
(PSZ)szTemp); 

ltoa(pFM->lExternalLeading,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_EXTERNALLEADING), 
(PSZ)szTemp); 

ltoa(pFM->lMaxBaselineExt,(PSZ)szTemp, 10 ); 

WinSetWindowText(WinWindowFromID(hWnd,DID_MAXBAS ELINEEXT), 
(PSZ)szTemp); 

ltoa(pFM->lEmHeight,(PSZ)szTemp, 10 ); 
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WinSetWindowText(WinWindowFromID(hWnd,DID_EMHEIGHT), 

(PSZ)szTemp); 

ltoa(pFM->lAveCharWidth,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_AVECHARWIDTH), 
(PSZ)szTemp); 

ltoa(pFM->lMaxCharInc,(PSZ)szTempj10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_MAXCHARINC), 
(PSZ)szTemp); 

ltoa( (pFM->lMaxBaselineExt - pFM->lInternall_eading), 
(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_POINT_SIZE), 
(PSZ)szTemp); 

ltoa(pFM->usCodePage,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd,DID_CODEPAGE), 
(PSZ)szTemp); 

sprintf(szTemp,"%s%s%s%s%s", 

szSelection[(pFM->fsSelection & FM_SEL_BOLD) ? 1 : 0], 

szSelection[(pFM->fsSelection & FM_SEL_ITALIC) ? 2 : 0], 

szSelection[(pFM->fsSelection & FM_SEL_STRIKEOUT) ? 3 : 0], 

szSelection[(pFM->fsSelection & FM_SEL_UNDERSCORE) ? 4 : 0] 3 

szSelection[(pFM->fsSelection & FM_SEL_OUTLINE) ? 5 : 0]); 

WinSetWindowText (WinWindowFroinID(hWnd,DID_SELECTION), 
(PSZ)szTemp); 

ltoa(pFM->sKerningPairs,(PSZ)szTemp,10); 

WinSetWindowText(WinWindowFromID(hWnd 3 DID_KERNPAIRS) 3 
(PSZ)szTemp); 

sprintf(szTemp,"%2i 3 %2i" 3 LOBYTE(pFM->sFamilyClass) 3 
HIBYTE(pFM->sFamilyClass)); 

WinSetWindowText(WinWindowFromID(hWnd,DID_FAMILYCLASS) 3 
(PSZ)szTemp); 

sprintf(szTemp,"%s", 

szSpacingt(pFM->fsType & FM_TYPE_FIXED) ? 1 : 0]); 

WinSetWindowText(WinWindowFromID(hWnd,DID_TYPE),(PSZ)szTemp); 

sprintf(szTemp,"%s%s", 

szFormat[(pFM->fsDefn & FM_DEFN_GENERIC) ? 1 : 0], 
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szType[(pFM->fsDefn & FM_DEFN_OUTLINE) ? 1 : 0]); 
WinSetWindowText(WinWindowFromID(hWnd,DID_DEFINITION), 

(PSZ)szTemp); 

WinSetWindowText(WinWindowFromID(hWnd,DID_CAPABILITIES), 

(PSZ) szQuality [ (pFiVI->f sCapabilities » 5)]); 

WinSetWindowText(WinWindowFromID(hWnd,DID_WEIGHTCLASS), 

(PSZ)szWeights[pFM->usWeightClass - 1 ]); 

WinSetWindowText(WinWindowFromID (hWnd, DID J/VIDTHCLASS), 

(PSZ)szWidths[pFM->usWidthClass - 1]); 
break; 

case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl),PVOIDFROMMP(mp2),CLR_PALEGRAY); 

mReturn = MRFROMLONG(0L); 

break; 

case WM_COMMAND: 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


MRESULT EXPENTRY ShearWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 


This dialog panel displays the currently selected font and its 
bounding box. Controls on the panel call the user to change the 
point size, character shear, character orientation and spacing. 


MRESULT mReturn = 0; 
BOOL bHandled = TRUE; 
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CHAR szTemp[20]; 

int iAngle; 

double dSine; 

double dCosine; 

SHORT sPos; 

switch(msg) 

{ 

case WM_INITDLG: 

CurrentCB.usSet = DISPLAY_FONT; 

charbox_from_pointsize (MAKEFIXED(0,DEFAULT_SIZE), 

&CurrentCB.sizfxCell); 

DefaultCharBox = CurrentCB.sizfxCell; 

ltoa (HIUSH0RT(CurrentCB.sizfxCell.cy),szTemp,10); 

WinSetDlgltemText(hWnd,DID_CHAR_HEIGHTj szTemp); 

ltoa (HIUSHORT(CurrentCB.sizfxCell.cx),szTemp,10); 

WinSetDlgltemText(hWnd,DID_CHAR_WIDTH,szTemp); 

init_sliders_n_spinners(hWnd); 

break; 

case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl) , PVOIDFROMMP(mp2) , CLR_PALEGRAY); 

mReturn = MRFROMLONG(0L); 

break; 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_RESET_SIZE: 

ltoa (HIUSHORT(DefaultCharBox.cy),szTemp,10); 
WinSetDlgltemText(hWnd,DID_CHAR_HEIGHT,szTemp); 
ltoa (HIUSHORT(DefaultCharBox.cx),szTemp,10); 
WinSetDlgltemText(hWnd,DID_CHAR_WIDTH,szTemp); 

WinSendMsg(hWnd,WM_COMMAND,MPFR0M2SH0RT(DID_APPLY,0),0); 
break; 

case DID_RESET_ANGLE: 

WinSendDlgltemMsg(hWnd,DID_ROT_ANGLE,SPBM_SETCURRENTVALUE, 
MPFROMLONG(0),0); 

WinSendMsg(hWnd,WM_COMMAND,MPFR0M2SH0RT(DID_APPLY,0),0); 
break; 

case DID_RESET_SHEAR: 

WinSendDlgltemMsg(hWnd,DID_SHEAR_ANGfc,SPBM_SETCURRENTVALUE, 
MPFROMLONG(90),0); 

WinSendMsg(hWnd,WM_COMMAND,MPFR0M2SH0RT(DID_APPLY,0),0); 
break; 

case DID_APPLY: 

WinQueryDlgltemText(hWnd,DID_CHAR_WIDTH,20,szTemp); 

CurrentCB.sizfxCell.cx = MAKEFIXED(atol(szTemp),0); 
WinQueryDlgltemText(hWnd,DID_CHAR_HEIGHT,20,szTemp); 
CurrentCB.sizfxCell.cy = MAKEFIXED(atol(szTemp),0); 
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WinQueryDlgltemText(hWnd,DID_ANGLEX,20,szTemp); 

CurrentCB.ptlAngle.x = atol(szTemp); 

WinQueryDlgltemText(hWnd,DID_ANGLEY,20,szTemp); 
CurrentCB.ptlAngle.y = atol(szTemp); 

WinlnvalidateRect (hWndClient,0,FALSE); 
break; 

} 

break; 

case WM_C0NTR0L: 

switch (LOUSHORT(mpl)) 

{ 

case DID_USER_TEXT: 

if (SH0RT2FR0MMP(mpl) == EN_CHANGE) 

{ 

WinQueryWindowText(HWNDFR0MMP(mp2),MAX_STR,szUserStr); 
WinlnvalidateRect (hWndClient,0,FALSE); 

} 

break; 

case DID_CHAR_EXTRA: 

sPos = (SHORT)WinSendDlgltemMsg(hWnd,DID_CHAR_EXTRA, 
SLM_QUERYSLIDERINFO, 

MPFR0M2SH0RT(SMA_SLIDERARMPOSITION,SMA_INCREMENTVALUE), 
0); 

CharExtra = MAKEFIXED(sPos - 10,0); 

WinlnvalidateRect (hWndClient,0,FALSE); 

WinllpdateWindow(hWndClient); 

break; 

case DID_BREAK_EXTRA: 

sPos = (SHORT)WinSendDlgltemMsg(hWnd,DID_BREAK_EXTRA, 
SLM_QUERYSLIDERINFO, 

MPFR0M2SH0RT(SMA_SLIDERARMPOSITION,SMA_INCREMENTVALUE), 
0); 

BreakExtra = MAKEFIXED(sPos - 10,0); 

WinlnvalidateRect (hWndClient,0,FALSE); 

WinUpdateWindow(hWndClient) ; 

break; 

case DID_ROT_ANGLE: 

if (SH0RT2FR0MMP(mpl) == SPBN_CHANGE) 

{ 

if (WinSendMsg((HWND)mp2,SPBM_QUERYVALUE,&iAngle, 
MPFR0M2SH0RT(0,SPBQJJPDATEIFVALID))) 

{ 

dRotSine = sin(TWO_PIE * iAngle / 360.0); 
dSine = 200.0 * dRotSine; 
dRotCosine = cos(TW0_PIE * iAngle / 360.0); 
dCosine = 200.0 * dRotCosine; 

CurrentCB.ptIAngle.x = ((LONG)dCosine * lHorzRes) / 

(LONG)IVertRes; 
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CurrentCB.ptlAngle.y = (LONG) dSine; 
ltoa (CurrentCB.ptlAngle.x,szTemp, 10); 
WinSetDlgltemText(hWnd,DID_ANGLEX,szTemp); 
ltoa (CurrentCB.ptIAngle.y,szTemp, 10); 
WinSetDlgltemText(hWnd,DID_ANGLEY,szTemp); 
WinlnvalidateRect (hWndClient,0,FALSE); 
WinllpdateWindow(hWndClient); 

} 

} 

break; 

case DID_SHEAR_ANGLE: 

if (SH0RT2FR0MMP(mpl) == SPBN_CHANGE) 

{ 

if (WinSendMsg ((HWND)mp2,SPBM__QUERYVALUE, &iAngle, 
MPFR0M2SH0RT(0,SPBCMJPDATEIFVALID))) 

{ 

dSine = 200.0 * sin(TWO_PIE * iAngle / 360.0); 
dCosine = 200.0 * cos(TWO_PIE * iAngle / 360.0); 
CurrentCB.ptlShear.x = ((LONG)dCosine * lHorzRes) / 
(LONG)IVertRes; 

CurrentCB.ptlShear.y = (LONG) dSine; 
ltoa (CurrentCB.ptlShear.x,szTemp, 10); 
WinSetDlgltemText(hWnd, DID_SHEARX,szTemp); 
ltoa (CurrentCB.ptlShear.y,szTemp,10); 
WinSetDlgltemText(hWnd, DID_SHEARY,szTemp); 
WinlnvalidateRect (hWndClient,0,FALSE); 
WinUpdateWindow(hWndClient); 

} 

} 

break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefDlgProc (hWnd,msg,mp1,mp2); 
return (mReturn); 

} 


BOOL APIENTRY init_sliders_n_spinners(HWND hWnd) 

/* .- .*\ 


This function will initalize the tick marks and text for the 
slider controls which control character and break character 
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spacing. A label is placed ever two tick marks. The spinners 
for rotation and shear angle are intialized by setting the 
range from 0 to 360 and the default angles are set. 


\*.*/ 

{ 

SHORT slndex; 

CHAR szTemp[4]; 

HWND hCharSliderWnd = WinWindowFromID(hWnd,DID_CHAR_EXTRA); 

HWND hBreakSliderWnd = WinWindowFromID(hWnd,DID_BREAK_EXTRA); 

HWND hRotAngleWnd = WinWindowFromID(hWnd,DID_ROT_ANGLE); 

HWND hShearAngleWnd = WinWindowFromID(hWnd,DID_SHEAR_ANGLE); 

for (slndex = -10;slndex <= 10 ;slndex ++) 

{ 

itoa(slndex,szTemp,10); 

WinSendMsg(hCharSliderWnd> SLM.SETTICKSIZE, 

MPFR0M2SH0RT(slndex + 10, 3), 0); 
if ((slndex & 0x01) == 0) 

WinSendMsg(hCharSliderWnd, SLM_SETSCALETEXT, 

MPFROMSHORT(slndex + 10), MPFROMP(szTemp)); 

WinSendMsg(hBreakSliderWnd, SLM_SETTICKSIZE, 

MPFR0M2SH0RT(slndex + 10, 3), 0); 


if ((slndex & 0x01) == 0) 

WinSendMsg(hBreakSliderWnd, SLM_SETSCALETEXT, 

MPFROMSHORT(slndex + 10), MPFROMP(szTemp)); 


WinSendMsg (hCharSliderWnd,SLM_SETSLIDERINFO, 

MPFR0M2SH0RT(SMA_SLIDERARMPOSITION,SMA_INCREMENTVALUE), 
MPFROMSHORT(10)); 

WinSendMsg (hBreakSliderWnd,SLM_SETSLIDERINFO, 

MPFR0M2SH0RT(SMA_SLIDERARMPOSITION,SMA_INCREMENTVALUE), 
MPFROMSHORT(10)); 


WinSendMsg(hRotAngleWnd,SPBM_SETLIMITS,(MPARAM)360,(MPARAM)0); 
WinSendMsg(hRotAngleWnd,SPBM_SETTEXTLIMIT,MPFROMSHORT(3),0); 
WinSendMsg(hRotAngleWnd,SPBM_SETCURRENTVALUE,MPFROMLONG(0),0); 

WinSendMsg(hShearAngleWnd,SPBM_SETLIMITS,(MPARAM)360,(MPARAM)0); 
WinSendMsg(hShearAngleWnd,SPBM_SETTEXTLIMIT,MPFR0MSH0RT(3),0); 
WinSendMsg(hShearAngleWnd,SPBM_SETCURRENTVALUE,MPFROMLONG(90),0); 

return (TRUE); 

} 
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PMFONT.H 


/* 


PM Font Header File 
Chapter 7 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define ID_APPNAME 1 

#define IDM_DISPLAY 300 
#define IDM_METRICS 301 
#define IDM_R0TATI0N 302 
#define IDM_AB0UT 303 

#define IDM_CHMODE 400 
#define IDM_CHM0DE_0NE 401 
#define IDM_CHMODE_TWO 402 
#define IDM_CHMODE_THREE 403 

#define IDM_ATTRIBUTE 550 
#define IDM_ATTR_ITALIC 551 
#define IDM_ATTR_BOLD 552 
#define IDM_ATTR_UNDERSCORE 553 
#define IDM_ATTR_STRIKEOUT 554 
#define IDM_ATTR_OUTLINE 555 

#define IDM_CODEPAGE 600 
#define IDM_CP037 037 
#define IDM_CP273 273 
#define IDM_CP274 274 
#define IDM_CP277 277 
#define IDM_CP278 278 
#define IDM_CP280 280 
#define IDM_CP282 282 
#define IDM_CP284 284 
#define IDM_CP285 285 
#define IDM_CP297 297 
#define IDM_CP437 437 
#define IDM_CP850 850 
#define IDM_CP852 852 
#define IDM_CP857 857 
#define IDM_CP860 860 
#define IDM_CP861 861 
#define IDM CP863 863 


364 





Chapter / Creating and Manipulating PM Fonts and Text 


#define IDM_CP865 865 
#define IDM_CP1004 1004 

#define IDS_APPNAME 1 
#define IDS_DISPLAY_TEXT 2 
#define IDS_SPECIAL_TEXT 3 
#define IDS USER TEXT 4 


#define DEFAULT_SIZE 30 
#define MAX_BUFF 128 

#define DISPLAY_FONT 1 

#define MAX_WIDTHS 9 

#define MAX_STR 40 

#define TW0_PIE (2.0 * 3.14159) 

#define WM_UPDATE_METRICS WM_USER + 1 

void APIENTRY cleanup(void); 

BOOL APIENTRY create_controls (HWND); 

BOOL APIENTRY create_font(HWND,int,PFONTMETRICS); 

void APIENTRY draw_grid(HPS,PRECTL); 

BOOL APIENTRY init_print_info (void); 

BOOL APIENTRY init_sliders_n_spinners(HWND); 

PFONTMETRICS APIENTRY init_font_LBox (HWND,HPS); 

USHORT APIENTRY post_error(HWND,USHORT); 

void APIENTRY print_selected_font (void); 

void APIENTRY process_paint(HWND,HPS); 

void APIENTRY process_command(HWND,MPARAM,MPARAM); 

void APIENTRY pr 0 CeSS_Contro1(HWND,HPSJMPARAM,MPARAM); 

void APIENTRY size_controls(MPARAM); 


PMFONT.RC 


/* 


PM Font Resource File 
Chapter 7 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, & and English 


*/ 


#include <os2.h> 
#include "chap7.h" 
#include "pmfont.h" 


RCINCLUDE pmfont.dig 
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RCINCLUDE ..\common\about.dig 

ICON ID_APPNAME PMFONT.ICO 

MENU ID_APPNAME 
BEGIN 

SUBMENU "-Display", IDM_DISPLAY 

BEGIN 

MENUITEM "Font Metrics", IDM_METRICS, 0, MIA_CHECKED 

MENUITEM "Rotation / Shear", IDM_ROTATION 

MENUITEM "About...", IDM_AB0UT 

END 

SUBMENU "-Charcter Mode", IDM_CHMODE 

BEGIN 

MENUITEM "Mode 1", IDM_CHMODE_ONE, 0, MIA_CHECKED 

MENUITEM "Mode 2", IDM__CHMODE_TWO 

MENUITEM "Mode 3", IDM_CHMODE_THREE 

END 

SUBMENU "Font Attribute", IDM_ATTRIBUTE 

BEGIN 

MENUITEM "Italic", IDM_ATTR_ITALIC 
MENUITEM "Bold", IDM_ATTR_BOLD 

MENUITEM "Underscore", IDM_ATTR_UNDERSCORE 
MENUITEM "Strikeout", IDM_ATTR_STRIKEOUT 
MENUITEM "Outline", IDM_ATTR_OUTLINE 

END 

SUBMENU "Code Page", IDM_CODEPAGE 

BEGIN 

MENUITEM "ASCII 437 US English", IDM_CP437 

MENUITEM "ASCII 850 Multilingual", IDM_CP850,0,MIA_CHECKED 

MENUITEM "ASCII 852 Multilingual", IDM_CP852 

MENUITEM "ASCII 857 Turkey", IDM_CP857 

MENUITEM "ASCII 860 Portugese", IDM_CP860 

MENUITEM "ASCII 861 Iceland", IDM_CP861 

MENUITEM "ASCII 863 French Canadian", IDM_CP863 

MENUITEM "ASCII 865 Norwegian", IDM_CP865 

MENUITEM "ASCII 1004 Desktop Publishing", IDM_CP1004 
MENUITEM "EBCDIC 037 US English", IDM_CP037, 

MIS_BREAKSEPARATOR 

MENUITEM "EBCDIC 273 Austrian/German", IDM_CP273 

MENUITEM "EBCDIC 274 Belgian", IDM_CP274 

MENUITEM "EBCDIC 277 Danish/Norwegian", IDM_CP277 

MENUITEM "EBCDIC 278 Finnish/Swedish", IDM_CP278 

MENUITEM "EBCDIC 280 Italian", IDM_CP280 

MENUITEM "EBCDIC 282 Portugese", IDM_CP282 
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MENUITEM "EBCDIC 284 Spanish", IDM_CP284 

MENUITEM "EBCDIC 285 UK-English", IDM_CP285 

END 

END 


STRINGTABLE PRELOAD MOVEABLE 
BEGIN 

IDS_APPNAME "PM Font Browser" 

IDS_DISPLAY_TEXT "AaBbCcDdEeFfGgHhliJjKkLIMmNnOoPpQqRr" 


"SsTtUuVvWwXxYyZz" 
IDS_SPECIAL_TEXT "aiounN^o^'" \«»« 
IDS_USER_TEXT "Sample Text String" 
END 


PMFONT.DLG 


/* 


Chapter 7 Dialogs 
Chapter 7 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGINCLUDE 1 "CHAP7.H" 

DLGTEMPLATE METRICS_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Fontrnetrics", METRICS_DLG, 105, 77, 210, 155, 
NOT FS_DLGBORDER 

PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 

GROUPBOX "Names", -1, 4, 127, 204, 27 


LTEXT 

"szFamilyname:", -1, 9, 138, 53, 

8 

LTEXT 

"szFacename:", -1, 9, 

129, 50, 8 

LTEXT 

"", DID FAMILYNAME, 78 

, 138, 127 

, 8 

LTEXT 

"", DID FACENAME, 78, 

129, 128, 

8 

GROUPBOX 

"Sizes", -1, 4, 61, 203, 64 


LTEXT 

"IMaxAscender", -1, 9, 

109, 60, 

8 

LTEXT 

"10", DID_MAXASCENDER, 

69, 109, 

20, 8 

LTEXT 

"lMaxDecender", -1, 9, 

100, 60, 

8 

LTEXT 

"10", DID_MAXDECENDER, 

69, 100, 

20, 8 

LTEXT 

"IMaxBaselineExt", -1, 

9, 91, 60 

, 8 

LTEXT 

”10", DID_MAXBASELINEEXT, 69, 91 

, 20, 

LTEXT 

"UnternalLeading", -1 

, 9, 82, 60, 8 
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LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

GROUPBOX 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

END 

END 


"10", DID_INTERNALLEADING, 69, 82, 20, 8 
"lExternalLeading", -1, 9, 73, 60, 8 
"10", DID_EXTERNALLEADING, 69, 73, 20, 8 
"lAveCharWidth", -1, 9, 64, 60, 8 
"10", DID_AVECHARWIDTH, 69, 64, 20, 8 
"lXHeight:", -1, 97, 109, 64, 8 
"10", DID_XHEIGHT, 169, 110, 20, 8 
"lEMHeight:", -1, 97, 100, 64, 8 
"10", DID_EMHEIGHT, 169, 101, 20, 8 
"lLowerCaseAscent", -1, 97, 91, 64, 8 
"10", DID_LOWERCASEASCENT, 169, 92, 20, 8 
"lLowerCaseDecent", -1, 97, 82, 64, 8 
"10", DID_LOWERCASEDECENT, 169, 83, 20, 8 
"lEmlnc", -1, 97, 73, 64, 8 
"10", DID_EMINC, 169, 74, 20, 8 
"IMaxCharInc", -1, 97, 64, 64, 8 
"10", DID_MAXCHARINC, 169, 65, 20, 8 
"Attributes", 4, 3, 2, 204, 59 
"Point Size", -1,9, 45, 49, 8 
"10", DID_POINT_SIZE, 69, 45, 20, 8 
"usCodePage", -1, 9, 35, 49, 9 
"850", DID_CODEPAGE, 69, 36, 20, 8 
"usSelection", -1, 9, 27, 49, 8 
"10", DESELECTION, 69, 27, 20, 8 
"sFamilyClass", -1, 9, 17, 49, 8 
"10", DID_FAMILYCLASS, 69, 18, 20, 8 
"sKerningPairs", -1, 9, 8, 53, 8 
"10", DIDJCERNPAIRS, 69, 9, 20, 8 
"usType", -1, 97, 44, 53, 8 
"10", DID_TYPE, 150, 45, 54, 8 
"usDefn", -1, 97, 36, 53, 8 
"10", DID_DEFINITION, 150, 36, 54, 8 
"usCapabilities", -1, 97, 28, 53, 8 
"10", DID_CAFV\BILITIES, i 50j 27, 54, 8 
"usWeightClass", -1, 97, 18, 53, 8 
"10", DID_WEIGHTCLASS, 150, 18, 54, 8 
"usWidthClass", -1, 97, 9, 53, 8 
"10", DID_WIDTHCLASS, 150, 9, 54, 8 


DLGTEMPLATE SHEAR_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "", SHEAR_DLG, 115, 55, 210, 157, NOT FS_DLGBORDER 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 

GROUPBOX "Character Size", -1, 3, 133, 204, 22 


568 



Chapter / Creating and Manipulating PM Fonts and Text 


LTEXT 

ENTRYFIELD 

LTEXT 

ENTRYFIELD 

PUSHBUTTON 

GROUPBOX 

LTEXT 

ENTRYFIELD 

LTEXT 

ENTRYFIELD 

PUSHBUTTON 

GROUPBOX 

LTEXT 

ENTRYFIELD 

LTEXT 

ENTRYFIELD 

PUSHBUTTON 

GROUPBOX 

LTEXT 

CONTROL 


LTEXT 

CONTROL 


GROUPBOX 

ENTRYFIELD 

DEFPUSHBUTTON 

LTEXT 

CONTROL 


LTEXT 

CONTROL 


END 

END 


"Height", -1, 7, 138, 28, 8 

"", DID_CHAR_HEIGHT, 37, 139, 16, 7, ESJ/IARGIN 
"Width", -1, 59, 138, 20, 8 

"", DID_CHAR_WIDTH, 90, 139, 16, 7, ESJ/IARGIN 

"Reset", DID_RESET_SIZE, 170, 136, 32, 12 

"Character Angle", -1, 3, 108, 204, 22 

"X Point", 6, 7, 112, 30, 8 

"1", DID_ANGLEX, 37, 113, 16, 7, ESJ/IARGIN 

"Y Point", 7, 59, 112, 27, 8 

"0", DID_ANGLEY, 90, 113, 16, 7, ESJ/IARGIN 

"Reset", DID_RESET_ANGLE, 170, 111, 32, 12 

"Character Shear", -1, 3, 83, 204, 22 

"X Point", 4, 7, 87, 26, 8 

"0", DID_SHEARX, 37, 89, 16, 7, ESJ/IARGIN 

"Y Point", -1, 59, 87, 26, 8 

"1", DID_SHEARY, 90, 88, 16, 7, ESJ/IARGIN 

"Reset", DID_RESET_SHEAR, 170, 86, 32, 12 

"Character Spacing", -1, 3, 40, 204, 41 

"Char Extra", -1, 7, 60, 38, 8 

"", DID_CHAR_EXTRA, 66, 60, 140, 16, WC_SLIDER, 

SLSJIORIZONTAL \ SLS_CENTER | SLS_LEFT | 

SLS_SNAPTOINCREMENT J SLS_HOMELEFT | 
SLS_PRIMARYSCALE1 | WS_GROUP ] WS_TABSTOP | 
WS_VISIBLE 

CTLDATA 12, 0, 21, 0, 0, 0 

"Break Char Extra", 9, 7, 44, 57, 8 

"", DID_BREAK_EXTRA, 67, 44, 138, 16, WC_SLIDER, 

SLS_HORIZONTAL | SLS_CENTER j SLS_LEFT j 

SLS_SNAPTOINCREMENT | SLS_HOMELEFT | 

SLS_PRIMARYSCALE1 J WS_GROUP | WS_TABSTOP | 

WS_VISIBLE 

CTLDATA 12, 0, 21, 0, 0, 0 

"Display Text", DID_POINTSIZE, 3, 14, 204, 22 
"" i DID__USER_TEXT, 12, 19, 134, 7, ESJ/IARGIN 
"Apply", DID_APPLY, 164, 17, 35, 12 
"Angle", -1, 112, 112, 20, 8 

"", DID_ROT_ANGLE, 133, 112, 30, 12, WC_SPINBUTTON, 
SPBS_ALLCHARACTERS | SPBS_NUMERICONLY | 

SPBS_MASTER j SPBS_SERVANT | SPBS_JUSTDEFAULT j 
SPBS_FASTSPIN | WS_GROUP j WS_TABSTOP j WS_VISIBLE 
"Angle", -1, 113, 88, 20, 8 

"", DID_SHEAR_ANGLE, 134, 87, 30, 12, WCJ3PINBUTTON, 
SPBS_ALLCHARACTERS | SPBS_NUMERICONLY | 

SPBS_MASTER j SPBS_SERVANT | 

SPBS_JUSTDEFAULT | SPBS_FASTSPIN | 

WS_GROUP | WS_TABSTOP j WS_VISIBLE 
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PMFONT.DEF 


NAME 

DESCRIPTION 

STACKSIZE 

EXPORTS 

PMFONT WINDOWAPI 

'PM Font Sample (c) 1993 

32768 

ClientWndProc 

MetricsWndProc 

ShearWndProc 

AboutDlgProc 

Blain, Delimon, & English' 

Font Class sFamilyClass 

The following list is based on the sFamilyClass field. It turns out that the high-word 
and low-word values determine the fonts. Though this is not documented any place, to 
our knowledge, these are the font mappings that we have been able to determine. 
For example, if the high-word value is 1 and the low-word value is 3, the font will be 
Venetian. 

High 

Word 

Low 

Word 

Resulting Font 

0 

Unclassified (No designation for font class or subclass has 
been assigned to this font) 

1 

OldStyle Serifs: 

1 

2 

3 

4 

5 

6 

7 

8 

IBM Rounded Legibility 

Garalde 

Venetian 

Modifed Venetian 

Dutch Modern 

Dutch Traditional 

Contemporary 

Calligraphic 

2 

Transitional Serifs: 

1 

2 

Direct Line 

Script 

3 

Modern Serifs: 

1 

2 

Italian 

Script 
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Clarendon Serifs: 
1 
2 

3 

4 

5 

6 
7 

Slab Serifs: 

1 

2 

3 

4 

5 

Reserved 

Freeform Serifs: 

1 

Sans Serifs: 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

Ornamentals: 

1 

2 

3 

4 


Clarendon 

Modern 

Traditional 

Newspaper 

Stub Serif 

Monotone 

Typewriter 


Monotone 

Humanist 

Geometric 

Swiss 

Typewriter 


Modern 

IBM Neo-Grotesque Gothic 
Humanist 

Low-x Round Geometric 
High-x Round Geometric 
Neo-Grotesque Gothic 
Modified Neo-Grotesque Gothic 
Reserved 
Reserved 

Typewriter Gothic 
Matrix 


Engraver 
Black Letter 
Decorative 
Three Dimensional 
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High 

Word 

10 


11 

12 


OS/2 2.i 


Low 

Word 

Resulting Font 

Scripts: 

1 

Unincal 

2 

Brush Joined 

3 

Formal Joined 

4 

Monotone Joined 

3 

Caligraphic 

6 

Brush Unjoined 

7 

Formal Unjoined 

8 

Reserved 

Monotone Unjoined 

Symbolic: 

1-2 

Reserved 

3 

Mixed Serif 

4-5 

Reserved 

6 

Oldstyle Serif 

7 

Neo-Grotesque Sans Serif 
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Introduction 

The OS/2 2.1 Technical Library says that initialization files (INI files) are “a convenient 
place to store information between sessions.” Sure, they are a place to keep stuff between 
instances of an application, but so is any other file. Their usefulness far exceeds that 
understatement. 

Initialization files are used to store important data between 
instances of an application. Often applications will keep par¬ 
ticular settings, directory structures, colors, or similar data in 
these files so that some continuity exists each time a particular 
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application is used. In this chapter, we want to reveal the usefulness of INI files and how 
to use that power for your own applications. You will learn how to use the profile man¬ 
agement API, which are the system functions used to manage OS/2 INI files. You will 
also have the framework for building a nontrivial OS/2 2.1 application. Best of all, you 
will have a usable INI file editor. 

An INI is like any other file. It is not hidden nor read only, nor does it need to be in 
any special place on the disk. INIs can be copied, renamed, deleted, and so on. Informa¬ 
tion can easily be added to or deleted from the file. OS/2 INI files, however, are binary, 
unlike those of Microsoft Windows that are in ASCII text. This makes OS/2 INI files a 
little less approachable. Rather than using just any text editor, you need one specifically 
created to work with these files. 

The OS/2 2.1 operating system provides a number of function calls to interact with 
INI files. For example, an application may want to save its current screen location and 
size. It should save this current screen location in an INI using functions from the profile 
management API. When the application is restarted, it should look for its INI file entry, 
again using functions from the profile management API. The application could then use 
the information it obtained from the INI file to resize itself accordingly. 

INI files are files built using the profile management API within OS/2. This profile 
management API should also be used to add information to an INI file as well as delete 
information. This means that a consistent format is provided with which you and your 
applications may interact with these files. This interaction can involve not only data spe¬ 
cific to the application, but also information contained within the operating system’s INI 
files, and even other applications’ data. 

An application may create its own INI file or use the system INIs. OS/2 uses two INI 
files to store system data and configuration information. OS2.INI and OS2SYS.INI are 
the default names for the user and system profile files. These files can be found in the 
OS/2 directory on the drive where OS/2 was installed. These files have a considerable 
number of entries. Configuration information for system display colors is kept there along 
with information for print queues, settings for the serial ports, and much more. 

Before we can start using INI files or programming for them, we have to learn their 
components. Even though INI files are binary files, all INI files that are created and 
modified using the Profile Management API have the same basic three-tiered layout. 

These levels have the names: 

Application name 
Key name 
Key data 

At the highest level of organization is the application name. An INI file may have 
one or more application names. Each application name may, in turn, have one or more 
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key names. Both the application name and the key name are null-terminated strings 
that may not exceed 1K, including the terminating NULL character. Each ke)^ name has 
a data stream associated with it. This is the key data. This key data may be a null- 
terminated string or a block of binary data. Blocks of binary data should not exceed 64K. 
For example, the default OS2INI file will contain the following: 

PM_colors <— Application name 

DialogBackground <--- Key name 

204 204 204 <--- Key data 

In this example, the key data is also a null-terminated string. It should be noted that 
case is preserved in all stored strings. 

One of the best ways to learn about the profile management API is to write an INI 
browser, as we have done here. Not only will this give you sample code for dealing with 
INI files, but also you will have a useful utility, especially because one is not provided 
with OS/2 2.1. The name of the INI browser we will be creating is INITOR. As always, 
if you intend to edit any system file, be sure to save a copy of that file in a safe place. One 
way of doing this is to let OS/2 automatically back up your current INI files each time 
you start your system. By adding the following line to your CONFIG.SYS file, you will 
always have a copy of your INI files as they existed at system start-up: 

CALL=C:\0S2\XC0PY.EXE C:\0S2\0S2*INI C:\0S2\*.BAK 

If your system boot drive is other than C, substitute the correct drive letter for your 
system. 


The Profile Management API 

Before we begin writing the INI file editor, let’s look at the profile management API. 
This is a relatively small collection of system functions that assists your interaction with 
INI files. This API is made up of the following entries: 


PrfCloseProfile 
PrfO pen Pro file 
PrfQueryProfile 

PrfQueryProfileData 

PrfQueryProfilelnt 

PrfQueryProfileSize 

PrfQueryProfileString 

PrfReset 

PrfW riteProfileData 
PrfW riteProfileString 


Closes a private profile file. 

Opens a private profile file. 

Retrieves full pathname for system initializa¬ 
tion files (OS2.INI and OS2SYS.INI). 
Retrieves information from the profile file. 
Retrieves an integer from the profile file. 
Retrieves the size to hold the desired informa¬ 
tion from the INI file. 

Retrieves a string from the profile file. 

Resets Presentation Manager initialization 
files with the new files. 

Writes or deletes binary data in the profile file. 
Writes or deletes a string in the profile file. 
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By the way, the term “profile file” is used almost interchangeably with the term “ini¬ 
tialization file.” Apparently, this follows a historical convention passed from Windows 
coding. 

Reading from or writing to an INI file requires an initialization file handle HINI. An 
INI file must be opened to retrieve an INI file handle. The user and system profile files 
are opened by the system at start-up or as a result of a call to the PrfReset function. 
Private INI files, however, must be opened using the PrfOpenPro file function. To access 
the system INI files, three predefined handles are supplied by the operating system. 

HINIJUSERPROFILE Read/Write user profile. 

HINI_SYSTEMPROFILE Read/Write system profile. 

HINI_PROFILE Read both user and system profile. Write user 

profile. 

Enumerating the Entries in the INI File 

Now that we have handles to access the system files, let’s look at the enum_app_names 
function in INITOR. It takes two parameters, an INI file handle and the ID (identifica¬ 
tion) of a string to load and set in the title bar. This ID is, as usual, defined in the re¬ 
source file. enum_app_names will enumerate all application names in the INI file by 
calling the PrfQueryProf ileString function. The application names are then added 
to the application list box displayed by the INITOR application. The 
PrfQueryProf ileString is defined as follows: 

PrfQueryProfileString 

(hlni,pAppName,pKeyName,pDefault,pBuffer,ulBufferSize) 


HINI 

hlni 

Initialization file handle. 

PSZ 

pAppName 

Pointer to a null-terminated string that 
identifies the application name to be queried. 

PSZ 

pKeyName 

Pointer to a null-terminated string that 
identifies the key name to be queried. 

PSZ 

p Default 

Pointer to a null-terminated string to be 
copied to pBuffer if the requested entry is not 
found. 

PSZ 

pBuffer 

Pointer to the location that the return string is 
to be copied. 

ULONG 

ulBuffSize 

Length in bytes of the memory pointed to by 
pBuffer. 


Prf Query Prof ileString performs a case-insensitive search for the string pointed 
to by pKeyName in the application section identified by pAppName. If a match is found, 
the key name data is copied to pBuffer and the number of bytes including the null 
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terminator copied is returned. If a match is not found, the contents of pDef ault are copied 
to pBuffer. If pBuffer is NULL, nothing is copied to pBuffer and 0 is returned. By 
specifying NULL for the pAppName parameter, PrfQueryProf ileString returns all 
application names in the INI file as an array of null-terminated strings. The last string 
will be double null-terminated. If NULL is passed as the pKeyName parameter and 
pAppName is the pointer to a string that is found in the file, all key names in that applica¬ 
tion section are returned as an array of null-terminated strings. As with the enumerated 
application names, the last string will be double null-terminated. 

Because the number and size of the entries in an INI file will vary, enum_app_names 
determines the space required to hold the application names by calling the 
Prf QueryProf ileSize function. Prf QueryProf ileSize takes a set of parameters similar 
to PrfQueryProfileString: 

PrfQueryProfileSize (hini,pAppName,pKeyName,pDataLength) 


HINI 

hlni 

Initialization file handle. 

PSZ 

pAppName 

Pointer to a null-terminated string that 
identifies the application name to be queried. 

PSZ 

pKeyName 

Pointer to a null-terminated string that 
identifies the key name to be queried. 

PULONG 

pDataLength 

Pointer to a ULONG that will contain the 
length of key name data if the function is 
successful. 


enum_app_names will pass NULL for both the pAppName and pKeyName because we 
want to know the memory required to hold all the application names: 

if (PrfQueryProfileSize(hini,NULL,NULL,(PULONG)&ulSize) && ulSize) 

If the function is successful and the length returned in ulSize is non-NULL, memory 
is allocated and the strings are retrieved: 

DosSubAlloc(pMem,(PPVOID)&pData,ulSize); 

if(PrfQueryProfileString(hini,NULL,NULL,"No Entries",pData,ulSize)) 

The strings are copied to the memory pointed to by pData, and the actual number of 
bytes (including NULLs) copied to pData is returned. Because we already know the length 
of the returned data, the return length is ignored. The application list box is disabled, 
and its contents are deleted. Disabling the list box prevents redrawing after each string is 
added: 

pCurrent = pData; 

WinEnableWindowUpdate(hAppLBox,FALSE); 

WinSendMsg (hAppLBox,LM_DELETEALL,NULL,NULL); 

The array of application names is walked, and each string is added to the list box in 
ascending order: 
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while (*pCurrent) 

{ 

WinSendMsg 

(hAppLBox,LM_INSERTITEM,(MPARAM)LIT_SORTASCENDING,(MPARAM)pCurrent); 
while(*pCurrent) 
pCurrent++; 
pCurrent++; 

} 

When all items are added, the first item is selected and updates to the list box are 
reenabled. The memory used for the application names is freed. By selecting an entry in 
the list box, a WM_C0NTR0L message with a notification code of LN_SELECT is sent to the 
owner window. The owner window, INITOR’s client, will call the enum_key_name func¬ 
tion that will fill up the key name list box in a similar fashion: 

WinSendMsg (hAppLBox,LM_SELECTITEM J MPFROMSHORT(0), 

MPFROMSHORT(TRUE)); 

WinEnableWindowUpdate(hAppLBox,TRUE); 

DosSubFree(pMem,pData,ulSize); 

After the key name list box is filled by the enum_key_name function, the first entry is 
selected causing another WM_C0NTR0L message to be sent to the owner window. This time 
the client window calls the get_key_data function. If a data item currently exists, the 
memory for it is freed, and the PrfQueryProf ileSize function is called to determine 
the storage requirements of the new data. The data is retrieved by calling the 
PrfQueryProfileData function because the data may be a null-terminated string or a 
stream of binary data. The Prf Query Prof ileData is defined as follows: 

PrfQueryProfileData(hlni,pAppName,pKeyName,pKeyData,(PULONG)&ulKeySize)) 


HINI 

hlni 

Initialization file handle. 

PSZ 

pAppName 

Pointer to a null-terminated string that 
identifies the application name to be queried. 

PSZ 

pKeyName 

Pointer to a null-terminated string that 
identifies the key name to be queried. 

PSZ 

pBuffer 

Pointer to the location that the data is 
to be copied. The return data is not null- 
terminated unless the last byte of the data 
stored was a NULL. 

PULONG 

pDataLength 

Pointer to a ULONG that contains the length 


of buffer pointed to by pBuffer. If the 
function is successful, the value will be 
replaced with the number of bytes actually 
copied to pBuffer. 
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As with the PrfQueryProf ileString function, the search is case-insensitive, and 
passing a NULL for either pAppName or PKeyName will have the same effect as described 
previously. If the data is successfully returned, the data window is invalidated causing the 
new data to be displayed. 


Adding Entries 

New application names, key names, and associated data may be added to an INI file with 
the PrfWriteProf ileData or PrfWriteProf ileSt ring functions. INITORadds new 
entries to system or private INI files using both functions, null-terminated strings may 
be added by selecting one of the menu options from the Add pop-up menu. Doing this 
will display a dialog that enables you to enter the application name, key name, and key 
data strings to add to the currently displayed INI file. The Add New Application option 
will leave all three edit windows uninitialized, and the Add New Key menu item will 
initialize the first edit window with the currently selected application name (see Figure 
8 . 1 ). 


Figure 8.1. 
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Because the application name and the key name may not exceed IK, the text limit 
for these edit controls is set to IK during the processing of the WM_INITDLG message: 

WinSendMsg(hAppWnd,EM_SETTEXTLIMIT,MPFROMSHORT(MAX_TITLE),0); 
WinSendMsg(hKeyWnd 3 EM_SETTEXTLIMIT,MPFROMSHORT(MAX_TITLE), 0); 

Because we are adding null-terminated strings to the current INI fide, the 
UPrfWriteProf ileSt ring function may be used. It is defined as follows: 


me 
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PrfWriteProfileString (hlni,pAppName,pKeyName,pBuffer) 

HINI hlni Initialization file handle. 

PSZ pAppName Pointer to a null-terminated string that 

identifies the application section to which 
data is to be added. If a section with this 
name does not currently exist, a new section 
with pAppName is added. Strings beginning 
with PM_ are reserved for system use and 
should not be used. 

PSZ pKeyName Pointer to a null-terminated string that 

identifies the key name section to which data 
is to be added. If a key with this name does 
not exist in the pAppName section, a new key 
with pKeyName is added. 

PSZ pBuffer Pointer to a null-terminated string that is 

associated with the pAppName pKeyName 
pair. If the pair existed prior to the call, the 
current string is replaced with the contents of 
pBuffer. Otherwise, the new string identified 
by pBuffer is added to the file. 

When all three edit fields in the Add dialog contain values and the Ok button is se¬ 
lected, the text will be queried from the three edit windows. The Add dialog will attempt 
to add the new entry to the current INI file with the PrfWriteProf ileString func¬ 
tion. Because the application name and key name used a fixed length buffer, only the size 
of the key data must be queried: 

WinQueryWindowText(hAppWnd,MAX_TITLE,szTitle); 

WinQueryWindowText(hKeyWnd,MAX_TITLE,szKey); 
ulLength = WinQueryWindowTextLength(hDataWnd); 

DosSubAlloc(pMem,(PPVOID)&pData,ulLength); 

if (pData && WinQueryWindowText(hDataWnd,ulLength,pData)) 

{ 

if (!(PrfWriteProfileString(hCurrentIni,szTitle,szKey,pData))) 

{ 

post_error(hWndDlg,ID_WRITE_ERROR); 

} 

DosSubFree(pMem,pData,ulLength); 

refresh_display(); 

} 

else 

post_error(hWndDlg,ID_QTEXT_ERROR); 

WinDismissDlg(hWndDlg,DID_OK); 
return 0; 
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If the strings are successfully added, the PrfWriteProf ileSt ring function will re¬ 
turn TRUE; otherwise, an error is posted. 

INITOR allows the initial size and location of the main window to be set by the user. 
When the screen location option is selected from the Save pop-up menu, the current 
window coordinates are queried and written to the user profile file using the 
PrfWriteProf i 1 eData function. This function takes the same parameters as 
PrfW riteProfileString with the addition of a buffer size, as shown here: 

PrfWriteProfileData (hlni,pAppName,pKeyName,pBuffer,ulBuffSize) 

ULONG ulBuffSize Length in bytes of the memory pointed to by 

pBuffer. 

The size parameter is used to specify the number of bytes pointed to by bBuf f er to 
write to the INI file. INITOR queries the window rectangle of the frame and then con¬ 
verts the points to screen coordinates. The application and key name strings are loaded, 
and the data is written to the INI file: 

WinQueryWindowRect(hWndFrame,(PRECTL)&Rectl); 

WinMapWindowPoints(hWndFrame,HWND_DESKTOP,(PPOINTL)&Rectl,1); 
WinLoadString (hab,0, ID__INITOR,MAX_TITLE, szTitle); 

WinLoadString (hab,0,ID_L0CATI0N,MAX_TITLE,szKey); 

if (!(PrfWriteProfileData(HINI_USERPROFILE,szTitle,szKey, 

(PVOID)&Rectl,sizeof(RECTL)))) 
post_error(hWnd,ID_SAVEPOS_ERROR); 

When INITOR is started, the entry defining the window location is queried from 
the user INI file by using the Prf QueryProf ileData function. If found, the initial win¬ 
dow size is set based on the saved coordinates; otherwise, the default screen location is 
used: 

WinLoadString (hab,0,ID_INIT0R,MAX_TITLE,szTitle); 

WinLoadString (hab,0,ID_LOCATION,MAX_TITLE,szKey); 

if 

(PrfQueryProfileData(HINIJJSERPROFILE,szTitle,szKey,(PVOID)&Rectl,(PULONG)&ulSize)) 
WinSetWindowPos (hWndFrame,HWND_TOP, 

Recti.xLeft,Recti.yBottom,Recti.xRight,Recti.yTop, 

SWP_SH0W ! SWP_ACTIVATE | SWP_ZORDER | SWP_SIZE | SWP_MOVE); 

else 

WinSetWindowPos (hWndFrame,HWND_T0P,0, 

WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - iClientHeight, 
WinQuerySysValue(HWND_DESKTOP,SV_CXSCREEN),iClientHeight, 
SWP_SH0W | SWP_ACTIVATE | SWP_ZORDER | SWP_SIZE J SWP_MOVE); 
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Deleting Entries 

You may have noticed that there does not seem to be a function to delete entries from 
the INI file. The functions that are used to add entries, PrfWriteProfileString and 
PrfWriteProf ileData, are also used to delete unwanted entries. An entire application 
section may be deleted by specifying the null-terminated application name and NULL 
for the key name and pBuf f er parameters: 

PrfWriteProfileString(hCurrentIni,pAppName,NULL,NULL); 

An application key pair may be deleted by specifying the null-terminated application 
and key name strings and NULL for the pBuff er parameters: 

PrfWriteProfileString(hCurrentIni,pAppName,pKeyName,NULL); 

Although the previous examples used the PrfWriteProf ileSting function, you may 
also use the PrfWriteProf ileData function with the same parameters along with a zero 
for the ulBuf f Size parameter. INITOR’s pop-up Delete menu enables you to delete an 
application section or remove a single key name. This option should be used with cau¬ 
tion when removing entries from the system or user INI files. Removing or changing a 
system entry could render your system unbootable. 

The INITOR Sample Application 

Before we begin to discuss the profile management API on which INITOR is based, we 
first want to tell you how the INITOR application code is organized. Like most OS/2 
2.1 applications, the executable is created from a familiar set of files, including a C mod¬ 
ule, a resource file, an icon file, and others. For the INITOR application, these files are 
as follows: 

INITOR.C 
INITOR.DEF 
INITOR.H 
INITOR.ICO 
INITOR.RC 
INITOR.DLG 

INITOR.C 

I* . 

Initor Program 


INITOR application’s C code. 
Module definition file. 

An include file. 

The application’s icon file. 
INITOR’s resource file. 
INITOR’s dialog definition file. 
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/ 
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#define INCL_WIN 
#define INCL_GPI 
#include <os2.h> 

//#include <string.h> 

#include <stdlib.h> 

#include "initor.h" 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY DataWndProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY AboutDlgProc(HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY AddDlgProc(HWND,ULONG,MPARAM,MPARAM); 

HAB hab; 

HWND hWndFrame, 
hWndClient, 
hAppLBox, 
hKeyLBox, 
hAppTitle, 
hKeyTitle, 
hDataTitle, 
hDataFrame, 
hDataWnd, 
hVScroll; 

PVOID pMem; 

PVOID pKeyData = NULL; 

ULONG ulKeySize = 0; 

HWND hButton[NUM_BUTTONS]; 

USHORT usSelectItem[NUM_BUTTONS] = 

{ 

IDM_ADD_KEYj 
IDM_DISPLAY_USERSYS, 

IDM__DELETE_KEY, 

IDM_SAVE_CHANGES, 

0 

}; 

HWND hPopupMenu [NUM_BUTTONS] = 

{ 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

}; 

HINI hCurrentlni = NULL; 

CHAR szTitle[MAX_TITLE]; 

CHAR szKey[MAX_TITLE]; 

CHAR szBuff1[MAX_BUFF]; 
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CHAR 

szBuff2[MAX_BUFF]; 


CHAR 

szFontFace[] 

"10.System Monospaced" 

CHAR 

szDataClass[] 

"DATA"; 

CHAR 

szClientClass[] = 

"CLIENT"; 

int 

nFixedFontWidth = 

0; 

int 

nFixedFontHeight = 

0; 

int 

nSysFontHeight; 


int 

iButtonWidth; 


int 

iButtonHeight; 


int 

iButtonY; 


int 

main() 



{ 

HMQ hmq; 

QMSG qmsg; 

RECTL Recti; 

ULONG ulSize = sizeof(RECTL); 

ULONG flFrameFlags = FCF__TITLEBAR | FCF_SYSMENU | 

FCF_SIZEBORDER j FCF_MINMAX | 

FCF_SHELLPOSITION | FCF_TASKLIST j 
FCF_NOBYTEALIGN; //N0TE2 

int iClientHeight; 

FRAMECDATA FrameData; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

DosAHocMem (&pMem, 8192, PAG_READ | PAG_WRITE) ; 

DosSubSet(pMern,DOSSUB_INIT | DOSSUB_SPARSE_OBJ,8192); 

// NOTE 3 

WinRegisterClass (hab, szClientClass, ClientWndProc,CS_SIZEREDRAW, 0); 
FrameData.cb = sizeof(FRAMECDATA); 

FrameData.flCreateFlags = flFrameFlags; 

FrameData.hmodResources = 0; 

FrameData.idResources = 0; 

WinLoadString (hab,0,ID_APPNAME,MAX_TITLE,szTitle); 

hWndFrame = WinCreateWindow (HWND_DESKTOP,WC_FRAME,szTitle,0L, 

0,0,0,0,HWND_DESKTOP,HWND_T0P,10,&FrameData,NULL); 

// NOTE 1 

WinSendMsg (hWndFrame,WM_SETICON, 

WinLoadPointer(HWND_DESKTOP,0,ID_APPNAME),0); 
hWndClient = WinCreateWindow (hWndFrame,szClientClass,szClientClass, 

WS_VISIBLE | WS_CLIPCHILDREN,0,0,0,0, 
hWndFrame,HWND_TOP,FID_CLIENT,NULL,NULL); 
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iClientHeight = WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - 
WinQuerySysValue(HWND_DESKTOP,SV_CYIC0N); 

WinLoadString (hab,0,ID_INITOR,MAX_TITLE,szTitle); 

WinLoadString (hab,0 3 ID_L0CATI0N,MAX_TITLE,szKey); 

if 

(PrfQueryProfileData(HINI_USERPROFILE,szTitle 3 szKey,(PVOID)&Rectl,(PULONG)&ulSize)) 
WinSetWindowPos (hWndFrame,HWND_T0P, 

Recti.xLeft 3 Recti.yBottom,Recti.xRight 3 Recti.yTop 3 
SWP_SHOW | SWP_ACTIVATE j SWP_ZORDER | SWP_SIZE | SWP_M0VE); 

else 

WinSetWindowPos (hWndFrame 3 HWND_TOP 3 0 3 

WinQuerySysValue(HWND_DESKTOP,SV_CYSCREEN) - iClientHeight, 
WinQuerySysValue(HWND_DESKTOP,SV_CXSCREEN),iClientHeight, 
SWP_SHOW | SWP_ACTIVATE | SWP_ZORDER j SWP_SIZE | SWP_MOVE); 

create_controls(hWndClient); 

WinShowWindow (hAppLBox,TRUE); 

WinShowWindow (hKeyLBox,TRUE); 
enum_app_names(HINI_PROFILE,ID_HINIBOTH); 

while (WinGetMsg (hab, &qmsg, NULL, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 


void APIENTRY change_ini_file(USHORT usCommand) 

/*.*\ 


This function changes the currently viewed INI file based on the 
usCommand value. If a system INI file is to be displayed the 
current INI file handle is set to one of the three system handles 
If a private INI file is to be displayed the file open dialog is 
posted allowing the user to select a file. If OK is selected and 
the file can be opened as an INI file it will become the current 
INI file viewed. The enum_app_names function is called to update 
the display. 



FILEDLG FileDlg; 

USHORT usStringID = 0; 

HINI hTempIni; 

HINI hPrevIni = hCurrentlni; 

USHORT usButtonNum = (USHORT)(usCommand - ID_FIRST_BUTTON); 
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usSelectItem[1] = usCommand; 
switch(usCommand) 

{ 

case IDM_DISPLAY_USER: 

hCurrentlni = HINIJJSERPROFILE; 
usStringID = ID_HINIUSER; 
break; 

case IDM_DISPLAY_SYS: 

hCurrentlni = HINI_SYSTEMPROFILE; 
usStringID = ID_HINISYS; 
break; 

case IDM_DISPLAY_USERSYS: 

hCurrentlni = HINI_PROFILE; 
usStringID = ID_HINIBOTH; 
break; 

case IDM_DISPLAY_PRIVATE: 

memset(&FileDlg,0,sizeof(FILEDLG)); 

FileDlg.cbSize = sizeof(FILEDLG); 

FileDlg.fi = FDS_CENTER | FDS_OPEN_DIALOG; 

FileDlg.pszTitle = "Select Private INI File"; 
strcpy (FileDlg.szFullFile,"*INI"); 

WinFileDlg(HWND_DESKTOP,hWndFrame,(PFILEDLG)&FileDlg); 
if ( (FileDlg.IReturn == DID_OK) && 

(hTempIni = PrfOpenProfile(hab,FileDlg.szFullFile)) ) 

{ 

if ( (hCurrentlni != HINIJ3YSTEMPR0FILE) && 
(hCurrentlni != HINIJJSERPROFILE) && 
(hCurrentlni != HINI_PROFILE) ) 

PrfCloseProfile(hCurrentlni); 
hCurrentlni = hTempIni; 

WinSetWindowText(hWndFrame,(PSZ)FileDlg.szFullFile); 

} 

break; 

} 

if (hPrevIni != hCurrentlni) 

enum_app_names(hCurrentlni,usStringID); 


void APIENTRY cleanup() 

/*.-.*\ 

This function is called to free the memory allocated, pop-up menus, 
and windows created for the application 


\*. 

{ 

int i; 


*/ 
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for (i = 0; i < NUM_MENUS; i++) 

WinDestroyWindow (hPopuplVlenu[i]); 
if (pKeyData) 

{ 

DosSubFree(pMem,pKeyData,ulKeySize); 
pKeyData = NULL; 
ulKeySize = 0; 

} 

DosFreeMem(pMem); 

WinDestroyWindow (hWndClient); 
WinDestroyWindow (hWndFrame); 


void APIENTRY create_controls(HWND hWndClient) 


This function will create the control windows which will display 
the application names, key names, and key data for INI files. The 
initial size is based on the size of their parent hWndClient. The 
pop-up menus used by INITOR are also loaded. 


\* 

{ 


RECTL 

int 

int 

int 

FRAMECDATA 

FONTMETRICS 

POINTL 

LONG 

HPS 

ULONG 


Recti; 

iButtonX; 

iColumn; 

i; 

FrameData; 

fontMetrics; 

Ptl[TXTBOX_COUNT +1]; 

IColor = CLR_PALEGRAY; 

hPS = WinGetPS(hWndClient); 

flFrameFlags = FCF_BORDER J FCF_NOBYTEALIGN ] 

FCF_VERTSCROLL; 


WinQueryWindowRect(hWndClient,(PRECTL)&Rectl); 
GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 
(PFONTMETRICS)&fontMetrics); 
nSysFontHeight = fontMetrics.IMaxBaselineExt + 2; 

WinLoadString (hab,0,ID_APPLICATION,MAX_TITLE,szTitle); 
hAppTitle = WinCreateWindow (hWndClient,WC_STATIC,szTitle, 
WS_VISIBLE ; SS_TEXT | DT_CENTER, 

0,Recti.yTop - nSysFontHeight, 

Recti.xRight / 2 - 1,nSysFontHeight, 
WinSetPresParam(hAppTitle,PP_BACKGROUNDCOLORINDEX, 
sizeof(PLONG),&lColor); 


*/ 
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WinLoadString (hab,0,ID_KEY,MAX_TITLE,szTitle); 
hKeyTitle = WinCreateWindow (hWndClient,WC_STATIC,szTitle, 
WS_VISIBLE | SS_TEXT | DT_CENTER, 

Recti.xRight / 2,Rectl.yTop - nSysFontHeight, 

Recti.xRight / 2 - 1,nSysFontHeight, 
hWndClient,HWND_T0P,1,NULL,NULL); 

WinSetPresParam(hKeyTitle,PP_BACKGROUNDCOLORINDEX, 
sizeof(PLONG),&lColor); 

WinLoadString (hab,0,ID_DATA,MAX_TITLE,szTitle); 
hDataTitle = WinCreateWindow (hWndClient,WC_STATIC,szTitle, 
SS_TEXT | DT_LEFT, 

0,Recti.yTop / 2, 

Recti.xRight,nSysFontHeight, 
hWndClient,HWND_T0P,1,NULL,NULL); 

WinSetPresParam(hDataTitle,PP_BACKGROUNDCOLORINDEX, 
sizeof(PLONG),&lColor); 

WinSetPresParam(hDataTitle,PP_FONTNAMESIZE,strlen(szFontFace)+1, 
(PVOID)szFontFace); 

hAppLBox = WinCreateWindow (hWndClient,WC_LISTBOX,NULL, 
LS_N0ADJUSTP0S, 

1,Recti.yTop / 2 + nSysFontHeight, 

Recti.xRight / 2 - 2,Recti.yTop / 2 - 

(nSysFontHeight *2+1), 

hWndClient,HWND_TOP,APP_LBOX,NULL,NULL) ; 

hKeyLBox = WinCreateWindow (hWndClient,WC_LISTBOX,NULL, 
LS_N0ADJUSTP0S, 

// NOTE 4 

(Recti.xRight / 2) + 1,Recti.yTop / 2 + nSysFontHeight, 
Recti.xRight / 2 - 2,Recti.yTop / 2 - 
(nSysFontHeight *2+1), 
hWndClient,HWND_TOP,KEY_LBOX,NULL,NULL); 

// Load the longest string to calculate button width 
WinLoadString (hab,0,ID_DISPLAY,MAX_TITLE,szTitle); 
GpiQueryTextBox(hPS,strlen(szTitle),szTitle,TXTBOX_COUNT,Ptl); 
iButtonWidth = Ptl[TXTBOX_CONCAT].x + 

(fontMetrics.lAveCharWidth * 2); 

iButtonHeight = nSysFontHeight + (nSysFontHeight / 3); 
iColumn = Recti.xRight / NUM_BUTTONS; 

iButtonX = (iColumn - iButtonWidth) / 2; 

iButtonY = nSysFontHeight / 2; 

WinRegisterClass (hab,szDataClass,DataWndProc,0,0); 

FrameData.cb = sizeof(FRAMECDATA); 

FrameData.flCreateFlags = flFrameFlags; 


533 



Chapter O Profile Management 


FrameData.hmodResources = 0; 

FrameData.idResources = 0; 

hDataFrame = WinCreateWindow (hWndClient ,WC_FRAME, 11 " ,0L, 

0 3 0,0,0 j hWndClient,HWND_T0P,11, &FrameData,NULL); 

hDataWnd = WinCreateWindow (hDataFrame,szDataClass,"" 3 
WS_VISIBLE 3 0 3 0 3 0 3 0, 

hDataFrame 3 HWND_TOP 3 FID_CLIENT 3 NULL,NULL); 

WinSetWindowPos (hDataFrame,HWND_TOP, 

1 3 iButtonHeight * 2,Recti.xRight - 2, 

Recti.yTop 12 - 2 - (iButtonHeight * 2), 

SWP_SHOW ! SWP_ZORDER | SWP_SIZE | SWP_M0VE); 

for (i = 0; i < NUM_BUTTONS; i++) 

{ 

WinLoadString (hab,0,ID_FIRST_BUTTON + i,MAX_TITLE,szTitle); 
hButton[i] = WinCreateWindow (hWndClient,WC_BUTTON,szTitle, 
WS_VISIBLE | BS_PUSHBUTTON, 

(iColumn * i) + iButtonX,iButtonY, 
iButtonWidth,iButtonHeight, 

hWndClient,HWND_TOP,ID_FIRST_BUTTON + i,NULL,NULL); 

} 

WinReleasePS(hPS); 

// Update the title 

WinSendMsg(hDataWnd,WM_U PDAT E_TITL E,0L,0L); 
WinShowWindow(hDataTitle,TRUE); 

for (i = 0; i < NUMJ/IENUS; i++) 

hPopupMenu[i] = WinLoadMenu(HWND_OBJECT,0,FIRST_MENU + i); 


} 


void APIENTRY enum_app_names(HINI hini,USHORT usStringID) 

/*..*\ 


This function will query the size required to hold all of the 
application names for the current INI file. If the file contains 
entries a temporary block of memory is allocated and the application 
names are queried from PM. The strings are then added to the 
application name list box and the memory if freed. The first entry 
in the list box is selected causing its owner, the client, to be 
notifed. The client window will then fill the key name list box 
by calling enum_key_name function. 


\* 

{ 


*/ 
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PVOID pData; 

PBYTE pCurrent; 

ULONG ulSize = 0L; 

if (PrfQueryProfileSize(hini,NULL,NULL,(PULONG)&ulSize) && ulSize) 

{ 

DosSubAlloc(pMem,(PPVOID)&pData 3 ulSize); 
if(PrfQueryProfileString(hini,NULL,NULL, 

"No Entries",pData,ulSize)) 

{ 

pCurrent = pData; 

WinEnableWindowUpdate(hAppLBox,FALSE); 

WinSendMsg (hAppLBox,LM_DELETEALL,NULL,NULL); 
while (*pCurrent) 

{ 

WinSendMsg 

(hAppLBox,LM_INSERTITEM,(MPARAM)LIT_SORTASCENDING,(MPARAM)pCurrent); 
while(*pCurrent) 
pCurrent++; 
pCurrent++; 

} 

WinSendMsg (hAppLBox,LMJ3ELECTITEM,MPFROMSHORT(0), 
MPFROMSHORT(TRUE)); 

WinEnableWindowUpdate(hAppLBox,TRUE); 
if (usStringID) 

{ 

WinLoadString (hab, 0 ,usStringID,MAX_TITLE,szTitle); 
WinSetWindowText(hWndFrame,(PSZ)szTitle); 

} 

} 

DosSubFree(pMem,pData,ulSize); 

} 

else 

{ 

WinAlarm(HWND_DESKTOP,WA_WARNING); 

WinEnableWindowUpdate(hAppLBox,FALSE); 

WinSendMsg (hAppLBox,LM_DELETEALL,NULL,NULL); 

WinSendMsg (hAppLBox,LM_INSERTITEM, 

(MPARAM)LIT_SORTASCENDING,"No Entries"); 

WinSendMsg (hAppLBox,LM_SELECTITEM, 

MPFROMSHORT(0),MPFROMSHORT(TRUE)); 

WinEnableWindowUpdate(hAppLBox,TRUE); 

// No entries exist force the data window to free up its 
// data buffer and repaint. 
get_key_data(" 

WinlnvalidateRect(hDataWnd,NULL,FALSE); 


} 


} 
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void APIENTRY get_key_data(PSZ pAppName,PSZ pKeyName) 

/* - -...*\ 


This function will attempt to query the keydata for the current 
application / key pair. If keydata currently exists it is freed 
before the new entry is queried. If successful a message is sent 
to the client to update the keydata windows title with the size 
of the new data, and the data window is invalidated. 


\*. .. -.*/ 

{ 

if (pKeyData) 

{ 

DosSubFree(pMem,pKeyData,ulKeySize); 
pKeyData = NULL; 
ulKeySize = 0; 

} 

if (PrfQueryProfileSize(hCurrentIni,pAppName,pKeyName, 
(PULONG)&ulKeySize) && ulKeySize) 

{ 

DosSubAlloc(pMem,(PPVOIDJ&pKeyData,ulKeySize); 
if(PrfQueryProfileData(hCurrentIni,pAppName,pKeyName, 
pKeyData,(PULONG)&ulKeySize)) 

{ 

// Update the title 

WinSendMsg(hDataWnd,WM_UPDATE_TITLE,0L,0L); 

// Force the data window to repaint 
WinlnvalidateRect(hDataWnd,NULL,FALSE); 

} 

} 

} 


void APIENTRY enum_key_name(PSZ pAppName) 


This function will query the size required to hold all of the 
key names for the current application name in the current INI file. 
If the application name contains key strings a temporary block of 
memory is allocated and the key names are queried from PM. The 
strings are then added to the application name list box and the 
memory if freed. The first entry in the list box is selected causing 
its owner, the client, to be notifed. The client window will then 
fill the data window by calling get_key_data. 


* 


*/ 
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PVOID pData; 

PBYTE pCurrent; 
ULONG ulSize = 0L; 
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if (PrfQueryProfileSize(hCurrentIni,pAppName,NULL,(PULONG)&ulSize) 
&& ulSize) 

{ 

DosSubAlloc(pMem,(PPVOID)&pData,ulSize); 
if(PrfQueryProfileString(hCurrentIni,pAppName,NULL,"No 
Entries",pData,ulSize)) 

{ 

pCurrent = pData; 

WinEnableWindowUpdate(hKeyLBox,FALSE); 

WinSendMsg (hKeyLBox,LM_DELETEALL,NULL,NULL); 
while (*pCurrent) 

{ 

WinSendMsg 

(hKeyLBox,LM_INSERTITEM,(MPARAM)LIT_SORTASCENDING,(MPARAM)pCurrent); 
while(*pCurrent) 
pCurrent++; 
pCurrent++; 

} 

WinSendMsg (hKeyLBox,LM_SELECTITEM,MPFROMSHORT(0), 
MPFROMSHORT(TRUE)); 

WinEnableWindowUpdate(hKeyLBox,TRUE); 

} 

DosSubFree(pMem,pData,ulSize); 

} 

else 

{ 

WinEnableWindowUpdate(hKeyLBox,FALSE); 

WinSendMsg (hKeyLBox,LM_DELETEALL,NULL,NULL); 
WinEnableWindowUpdate(hKeyLBox,TRUE); 

//No entries exist force the data window to free up its 
// data buffer and repaint. 
get_key_data("",""); 

WinlnvalidateRect(hDataWnd,NULL,FALSE); 

} 


void APIENTRY size_controls(MPARAM INewSize) 

/*.*\ 

Since the children are scaled to the client window size this function 
is called when the client window receives a WM_SIZE message. All 
child windows are resized to fit the new client size. The buttons 
will be repositioned but will not overlap. 


SHORT sNewWidth = SH0RT1FROMMP(INewSize); 
SHORT sNewHeight = SH0RT2FR0MMP(INewSize); 
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int 

iButtonX 

int 

iColumn; 

int 

i; 


WinSetWindowPos (hAppTitle,HWND_T0P, 

0,sNewHeight - nSysFontHeight,sNewWidth / 2 - 1,nSysFontHeight, 
SWP_SIZE | SWP_M0VE); 

WinSetWindowPos (hKeyTitle,HWND_T0P, 

sNewWidth / 2,sNewHeight - nSysFontHeight,sNewWidth / 2 - 
1,nSysFontHeight, 

SWP_SIZE | SWP_M0VE); 

WinSetWindowPos (hDataTitle,HWND_T0P, 

0,sNewHeight / 2,sNewWidth,nSysFontHeight, 

SWP_SIZE | SWP_M0VE); 

WinSetWindowPos (hAppLBox,HWND_T0P, 

1,sNewHeight / 2 + nSysFontHeight, 

sNewWidth / 2 - 2,sNewHeight / 2 - (nSysFontHeight *2+1), 
SWP_SIZE | SWPJ/IOVE); 

WinSetWindowPos (hKeyLBox,HWND_T0P, 

sNewWidth / 2 + 1,sNewHeight / 2 + nSysFontHeight, 
sNewWidth / 2 - 2,sNewHeight / 2 - (nSysFontHeight *2+1), 
SWP_SIZE | SWP_M0VE); 

iColumn = (max (sNewWidth,iButtonWidth * NUM_BUTTONS)) / 
NUM_BUTTONS; 

iButtonX = (iColumn - iButtonWidth) / 2; 

for (i = 0; i < NUM_BUTTONS; i++) 

WinSetWindowPos (hButton[i],HWND_TOP, 

(iColumn * i) + iButtonX,iButtonY,0,0,SWP_M0VE); 

WinSetWindowPos (hDataFrame,HWND_T0P, 

1,iButtonHeight * 2,sNewWidth - 2, 
sNewHeight 12 - 2 - (iButtonHeight * 2), 

SWP_SHOW | SWP_ZORDER | SWP_SIZE | SWP_M0VE); 


USHORT APIENTRY post_error(HWND hWnd,USHORT usErrorlD) 

/*.*\ 


This is a utility function which will post a message box with 
a string loaded from the resource file. 


\*.*/ 

{ 

WinLoadString (hab,0,usErrorID,MAX_BUFF,szBuff1); 
return (WinMessageBox(HWND_DESKTOP,hWnd,szBuff1, 






(PSZ)"Error" 3 0 3 MB_OK | MB_ICONHAND j MB_APPLMODAL)); 


void APIENTRY process_command(HWND hWnd 3 MPARAM mpl 3 MPARAM mp2) 


/*-----*\ 

All WM_COMMAND messages received by the client window will be 
processed here. For each button command a popup menu is displayed. 

\*--*/ 

{ 

PVOID pKey; 


RECTL Recti; 

USHORT usSelection; 

USHORT usAddCmd = IDM_ADD_KEY; 

USHORT usCommand = SHORT1FROMMP(mpl); 

USHORT usButtonNum = (USHORT)(usCommand - ID_FIRST_BUTTON); 

switch(usCommand) 

{ 

case ID_DELETE: 
case ID_DISPLAY: 
case ID_ADD: 
case ID_SAVE: 

WinQueryWindowRect (hButton[usButtonNum] 3 (PRECTL)&Rectl); 
WinMapWindowPoints(hButton[usButtonNum] 3 hWndFrame, 

(PPOINTL)&Rectl 3 2); 

WinPopupMenu(hWndFrame 3 hWndClient,hPopupMenu[usCommand - 
ID_FIRST_BUTTON], 

Recti.xLeft + 1 3 Rectl.yTop + 1, 
usSelectltemfusButtonNum], 

PU_HCONSTRAIN | PU_VCONSTRAIN | PU_KEYBOARD | 
PU__MOUSEBUTTON1 | PU_SELECTITEM) ; 
break; 

case ID_EXIT: 

WinPostMsg(hWndFrame 3 WM_QUIT 3 0,0); 
break; 

case IDM_ADD_APP: 

usAddCmd = IDM_ADD_APP; 
case IDM_ADD_KEY: 

usSelectItem[0] = usCommand; 

WinDlgBox(HWND_DESKTOP 3 hWndFrame 3 (PFNWP)AddDlgProc 3 0,ADD_DLG 3 
(PVOID)&usAddCmd); 
break; 
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case IDM_AB0UT: 

WinDlgBox(HWND_DESKTOP,hWndFrame,(PFNWP)AboutDlgProc,0,AB0UT_DLG, 
(PVOID)&usAddCmd); 
break; 

case IDM_REFRESH: 

// enum_app_names(hCurrentIni,0); 

refresh_display(); 
break; 

case IDMJDISPLAYJJSER: 
case IDM_DISPLAY_SYS: 
case IDM_DISPLAY_USERSYS: 
case IDM_DISPLAY_PRIVATE: 

if ( (usSelectItem[1] != usCommand) |j 

(usCommand == IDM_DISPLAY_PRIVATE) ) 

{ 

change_ini_file(usCommand); 

} 

break; 

case IDM_DELETE_APP: 
case IDM_DELETE_KEY: 

usSelectItem[2] = usCommand; 

usSelection = (USHORT)WinSendMsg (hAppLBox,LM_QUERYSELECTION, 
MPFROMSHORT(LIT_FIRST),NULL); 
if (usSelection != LIT_N0NE) 

{ 

WinSendMsg(hAppLBox,LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(usSelection,MAX_TITLE),MPFROMP(szTitle)); 
if (usCommand == IDM_DELETE_KEY) 

{ 

usSelection = (USHORT)WinSendMsg 
(hKeyLBox,LM_QUERYSELECTION, 

MPFROMSHORT(LIT_FIRST),NULL); 

WinSendMsg(hKeyLBox,LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(usSelection,MAX_TITLE),MPFROMP(szKey)); 
pKey = szKey; 

> 

else 

pKey = NULL; 

if (!(PrfWriteProfileString(hCurrentlni, 
szTitle,pKey,NULL))) 

{ 

post_error(hWnd,ID_DELETE_ERROR); 

} 

refresh_display(); 

} 

else 

WinAlarm(HWND_DESKTOP,WA_N0TE); 
break; 
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case IDM_SAVE_CHANGES: 

usSelectItem[3] = usCommand; 
break; 

case IDM_SAVE_LOCATION: 

usSelectItem[3] = usCommand; 

WinQueryWindowRect(hWndFrame,(PRECTL)&Rectl); 
WinMapWindowPoints(hWndFrame,HWND_DESKTOP,(PPOINTL)&Rectl, 1) 
WinLoadString (hab,0,ID_INIT0R,MAX_TITLE,szTitle); 

WinLoadString (hab,0,ID_LOCATION,MAX_TITLE,szKey); 
if (!(PrfWriteProfileData(HINI_USERPROFILE,szTitle,szKey, 
(PVOID)&Rectl,sizeof(RECTL)))) 
post_error(hWnd,ID_SAVEPOS_ERROR); 
refresh_display(); 
break; 

} 

} 

void APIENTRY process_control(HWND hWnd,MPARAM mpl,MPARAM mp2) 

/*.*\ 


This function will handle the control notifications passed to 
the client window in the WM_C0NTR0L message. When an item is 
selected in the application or key name list boxes, the remaining 
list boxes and controls are updated. 


\* */ 

{ 

USHORT usSelection; 

if (SH0RT2FR0MMP(mpl) == LN_SELECT) 

{ 

usSelection = (USHORT)WinSendMsg (hAppLBox,LM_QUERYSELECTION, 
MPFROMSHORT(LIT_FIRST),NULL); 

WinSendMsg(hAppLBox,LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(usSelection,MAX_TITLE), 

MPFROMP(szTitle)); 
switch (LOUSHORT(mpl)) 

{ 

case APP_LB0X: 

enum_key_name(szTitle); 
break; 

case KEY_LB0X: 

usSelection = (USHORT)WinSendMsg (hKeyLBox, 
LM_QUERYSELECTION, 

MPFROMSHORT(LIT_FIRST),NULL); 

WinSendMsg(hKeyLBox,LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(usSelection,MAX_TITLE), 

MPFROMP(szKey)); 
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get_key_data(szTitle,szKey); 
break; 

} 

} 

} 

void APIENTRY refresh_display() 

/* *\ 


This is a utility that causes the current INI file to be reread 
and updated on the display. The current selection is saved and 
restored after the update. This prevents the list box from scrolling 
to the top after updating an entry. 


\*.*/ 

{ 

USHORT usCurrApp = (USHORT)WinSendMsg(hAppLBox, 

LM_QUERYSELECTION,0,0) ; 

USHORT usCurrKey = (USHORT)WinSendMsg(hKeyLBox, 

LM_QUERYSELECTION,0,0); 

enum_app_names(hCurrentIni,0); 

WinSendMsg 

(hAppLBox,LM_SELECTITEM,MPFROMSHORT(usCu rrApp),MPFROMSHORT(TRUE)); 
WinSendMsg 

(hKeyLBox,LM_SELECTITEM,MPFROMSHORT(usCurrKey),MPFROMSHORT(TRUE)); 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

/*.*\ 


This is the application callback which handles the messages 
necessary to INITOR. 


\*.*/ 

{ 

HPS hps; 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,NULL,NULL); 

WinEndPaint (hps); 
break; 
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case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl),PVOIDFROMMP(mp2),CLR_PALEGRAY) 
mReturn = MRFROMLONG(0L); 
break; 

case WM_COMMAND: 

process_command(hWnd,mp1,mp2); 
break; 

case WM_CONTROL: 

process_control(hWnd,mp1,mp2); 
break; 

#ifdef LATER 

case WM_QUERYTRACKINFO: 

{ 

PTRACKINFO pti = (PTRACKINF0)mp2; 

pti->ptlMinTrackSize.x = iButtonWidth * NUM_BUTTONS; 
pti->ptlMinTrackSize.y = iButtonHeight * 5; 

} 

break; 

#endif 

case WM_SIZE: 

size_controls(mp2); 
break; 

case WM_DESTROY: 
cleanup(); 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 

} 


MRESULT EXPENTRY AboutDlgProc(HWND hWndDlg,ULONG ulMessage,MPARAM 
mpl,MPARAM mp2) 
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/* 


*\ 


This is the callback for the application information dialog. 


\*.*/ 

{ 

switch (ulMessage) 

{ 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_0K: 

WinDismissDlg(hWndDlg,DID_0K); 
return 0; 

} 

break; 

} 

return (WinDefDlgProc(hWndDlg,ulMessage,mpl,mp2)); 


MRESULT EXPENTRY AddDlgProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2) 

/*.....*\ 

This is the callback for the dialog which allows you to add items 
to the current INI file. It will disable the OK button until all 
three edit fields contain text. 


\*.*/ 

{ 

static HWND hAppWnd; 
static HWND hKeyWnd; 
static HWND hDataWnd; 

USHORT usSelection; 

USHORT usAddCmd; 

ULONG ulLength; 

PVOID pData = NULL; 

switch (ulMessage) 

{ 

case WM_INITDLG: 

hAppWnd = WinWindowFromID(hWndDlg,DID_APP_NAME); 
hKeyWnd = WinWindowFromID(hWndDlg,DID_KEY_NAME); 
hDataWnd = WinWindowFromID(hWndDlg,DID_KEY_DATA); 
usAddCmd = *((PUSH0RT)mp2); 

WinSendMsg(hAppWnd,EM_SETTEXTLIMIT,MPFROMSHORT(MAX_TITLE),0); 
WinSendMsg(hKeyWnd,EM_SETTEXTLIMIT,MPFROMSHORT(MAX_TITLE),0); 
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usSelection = (USHORT)WinSendMsg (hAppLBox,LM_QUERYSELECTION, 
MPFROMSHORT(LIT_FIRST),NULL); 

if ((usSelection != LIT_NONE) && (usAddCmd == IDM_ADD_KEY)) 

{ 

WinSendMsg(hAppLBox,LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(usSelection,MAX_TITLE),MPFR0MP(szTitle)); 
WinSetWindowText(WinWindowFromID(hWndDlg,DID_APP_NAME), 
szTitle); 

WinSendMsg(hAppWnd,EM_SETREADONLY,MPFROMSHORT(TRUE),0); 
WinSetFocus(HWND_DESKTOP,hKeyWnd); 
return ((MPARAM)1); 

} 

break; 

case WM_CONTROL: 

if ( (SH0RT2FR0MMP(mpl) == EN_CHANGE) || 

(SH0RT2FR0MMP(mp1) == MLN_CHANGE) ) 

{ 

if ( (WinQueryWindowTextLength(hAppWnd)) && 
(WinQueryWindowTextLength(hKeyWnd)) && 
(WinQueryWindowTextLength(hDataWnd)) ) 
WinEnableWindow(WinWindowFromID(hWndDlg,DID_OK),TRUE); 
else 

WinEnableWindow(WinWindowFromID(hWndDlg,DID_OK),FALSE); 

} 

break; 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_OK: 

WinEnableWindow(WinWindowFromID(hWndDlg,DID_OK),FALSE) 
WinQueryWindowText(hAppWnd,MAX_TITLE,szTitle); 
WinQueryWindowText(hKeyWnd,MAX_TITLE,szKey); 
ulLength = WinQueryWindowTextLength(hDataWnd); 
DosSubAlloc(pMemj(PPVOID)&pData,ulLength); 

if (pData && WinQueryWindowText 
(hDataWnd,ulLength,pData)) 

{ 

if 

(!(PrfWriteProfileString(hCurrentIni 3 szTitle,szKey,pData))) 

{ 

post_error(hWndDlg,ID_WRITE_ERROR); 

} 

DosSubFree(pMem,pData,ulLength); 
refresh_display(); 


} 
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else 

post_error(hWndDlg 3 ID_QTEXT_ERROR); 
WinDismissDlg(hWndDlg,DID_0K); 
return 0; 

} 

break; 

} 

return (WinDefDlgProc(hWndDlg,ulMessage,mpl,mp2)); 

> 


MRESULT EXPENTRY DataWndProc (HWND hWnd, ULONG msg, M PAR AM mpl , 

MPARAM mp2) 

/*..*\ 


This is the callback for INITOR's private data display window. 

It will display data in both HEX and ASCII and allows scrolling. 

\* 

{ 


switch (msg) 

{ 

case WM_CREATE: 

hPS = init_data_window(hWnd); 

hVScroll = WinWindowFromID(hDataFrame,FID_VERTSCROLL); 
break; 

case WM_PAINT: 

iNumLines = paint_data_window(hWnd,hPS,iTopLine); 

WinSendMsg(hVScroll,SBM_SETSCROLLBAR,MPFROMSHORT(iTopLine), 
MPFR0M2SH0RT(1 3 iNumLines)); 
break; 

case WM_VSCROLL: 

switch (SH0RT2FR0MMP(mp2)) 

{ 

case SB_LINEDOWN: 

if (iTopLine < iNumLines) 

{ 

iTopLine++; 

WinlnvalidateRect(hDataWnd,NULL,FALSE); 

} 


static HPS hPS; 


static int 
static int 
static int 
BOOL 
MRESULT 


iWndHeight; 
iNumLines; 
iTopLine = 1; 
bHandled = TRUE; 
mReturn = 0: 
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break; 

case SB_LINEUP: 

if (iTopLine > 1) 

{ 

iTopLine- - ; 

WinlnvalidateRect(hDataWnd,NULL,FALSE); 

} 

break; 

case SB_SLIDERTRACK: 

if ((SH0RT1FR0MMP(mp2) >= 1) j| (SH0RT1FROMMP(mp2)) 

<= iNumLines) 

{ 

iTopLine = SH0RT1FROMMP(mp2); 

WinlnvalidateRect(hDataWnd,NULL,FALSE); 

} 

else 

WinAlarm(HWND_DESKTOP,WA_NOTE); 
break; 

} 

break; 

case WM_ERASEBACKGROUND: 

WinFillRect((HPS)LONGFROMMP(mpl), 

PVOIDFROMMP(mp2),CLR_WHITE); 
mReturn = MRFROMLONG(0L); 
break; 

case WM_SIZE: 

iWndHeight = SH0RT2FR0MMP(mp2); 
break; 

case WM_UPDATE_TITLE: 

WinLoadString (hab,0,ID_DATA,MAX_BUFF,(PSZ)szBuffl); 
sprintf(szBuff2,szBuff1,ulKeySize,ulKeySize); 
WinSetWindowText(hDataTitle,(PSZ)szBuff2); 
break; 

case WM_DESTROY: 

GpiDeleteSetId(hPS,FIXED_FONT_LCID); 

GpiAssociate(hPS,NULL); 

GpiDestroyPS(hPS); 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
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return (mReturn); 

} 


HPS APIENTRY init_data_window(HWND hWnd) 

/*.-.*\ 


This function will intialize the data window by creating a PS 
and create a Monospaced system font. The default attributes and 
the font are set into the PS. 


\*.*/ 

{ 

HPS hPS = NULL; 

SIZEL sizel; 

FATTRS 1 fattr; 

FONTMETRICS FontMetrics; 

ULONG ulCount = 1; 


} 


sizel.cx = sizel.cy = 0; 

if (hPS = GpiCreatePS(hab,WinOpenWindowDC(hWnd), 

(PSIZEL)&sizel,PU_PELS | GPIF_DEFAULT | GPIT_MICRO | 
GPIA_ASSOC)) 

{ 


fattr.usRecordLength 
fattr.fsSelection 
fattr.IMatch 
fattr.idRegistry 
fattr.usCodePage 
fattr.IMaxBaselineExt 
fattr.lAveCharWidth 
fattr.fsType 
fattr.fsFontUse 


sizeof(FATTRS); 
0 ; 

0 ; 

0 ; 

0 ; 

16 ; 

8 ; 

0 ; 

0 ; 


strcpy(fattr.szFacename,"System Monospaced"); 

GpiCreateLogFont (hPS,NULL,FIXED_FONT_LCID,&fattr); 
GpiSetCharSet(hPS,FIXED_FONT_LCID); 

GpiQueryFontMetrics(hPS,(long)sizeof(FONTMETRICS),&FontMetrics) 
nFixedFontWidth = FontMetrics.lAveCharWidth; 


nFixedFontHeight = FontMetrics.IMaxBaselineExt; 
GpiSetBackMix(hPS,BM_OVERPAINT); 


} 

return (hPS); 


int APIENTRY format_line(PSZ pRetBuff,PSZ pData,int iLineNum,int 
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iLineSize) 

. *\ 

This function will take the data in pData for and format iLineSize 
bytes of the data as HEX and ASCII in pRetBuff. 


*/ 


PSZ pCurData = pData; 

PSZ pCurRet; 
int i; 
int iLength; 

// Format the offset from the start of data 
i = sprintf(pRetBuff,"%04X: ",(iLineNum - 1) * 16); 

// Set the remaining bytes to spaces 
pCurRet = pRetBuff + i; 
memset(pCurRet, 1 ',80); 

// Format the data as HEX 
pCurRet = pRetBuff + HEX_START; 
for (i = 0; i < iLineSize; i++) 

{ 

if (*(pData + i) < 16) 

{ 

*pCurRet++ = 1 0 1 ; 

ultoa((ULONG)*(pData + i),pCurRet,16); 
pCurRet += 1; 

} 

else 

{ 

ultoa((ULONG)*(pData + i),pCurRet,16); 
pCurRet += 2; 

} 

if (i == 7) 

*pCurRet++ = '- 1 ; 

else 

*pCurRet++ = 1 1 ; 

} 

// Format the data as an ASCII string 
pCurRet = pRetBuff + ASCII_START; 

*pCurRet++ = ’>'; 

for (i = 0; i < iLineSize; i++) 

{ 

if ((*(pData + i) >= 32) && (*(pData + i) <= 128)) 
*(pCurRet + i) = *(pData + i); 

else 


(pCurRet + i) = 
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} 

*(pCurRet + iLineSize) = 
*(pCurRet + iLineSize + 1) = 1 \0' ; 

iLength = strlen(pRetBuff); 
return (iLength); 


int APIENTRY paint_data_window(HWND hWnd,HPS hPS,int iStartLine) 
/*. 


This function will handle the painting of the data window. The 
data is output after being formated by format_line. A maximum 
of 16 bytes are displayed per line. The first line displayed 
is determined by iStartLine. 


\*. 

{ 

RECTL Recti; 

PSZ pData; 

POINTL ptl; 

int i,j; 

int iSize; 

int iPartialLine; 

int iLineLength = MAX_LINE; 

int iNumLines = ulKeySize / MAX_LINE; 

hPS = WinBeginPaint (hWnd,hPS,&Rectl); 

WinFillRect (hPS,&Rectl,CLR_WHITE); 

WinQueryWindowRect(hWnd,&Rectl); 
if ((ulKeySize) && (pKeyData)) 

{ 

if (iPartialLine = ulKeySize % MAX_LINE) 
iNumLines++; 

ptl.x = Recti.xLeft + nFixedFontWidth; 

pData = (PSZ)pKeyData + ((iStartLine - 1) * 16); 

for (j = l,i = iStartLine; i <= iNumLines; i++ 3 j++) 

{ 

ptl.y = (Recti.yTop - nSysFontHeight * j); 
if ((i == iNumLines) && (iPartialLine)) 
iLineLength = iPartialLine; 

iSize = format_line(szBuff1,pData,i,iLineLength); 
GpiCharStringAt (hPS,&ptl,iSize,szBuffl); 
pData += iLineLength; 

} 
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} 

WinEndPaint (hPS); 
return (iNumLines); 


INITOR.DEF 


NAME 

DESCRIPTION 

PROTMODE 

STUB 

HEAPSIZE 
STACKSIZE 
EXPORTS 


INITOR WINDOWAPI 

'OS/2 INI Editor Program Blain, Delimon, & English, 1993' 

1 os2stub. exe 1 

4096 

32768 

ClientWndProc 

DataWndProc 

AboutDlgProc 


INITOR.H 

/* . 


Initor Header File 


*/ 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


#define 

ID_ 

APPNAME 

51 

#define 

ID_ 

APPLICATION 

52 

#define 

ID_ 

]key 

53 

#define 

id] 

]data 

54 

#define 

id" 

HINIUSER 

55 

#define 

ID_ 

]hinisys 

56 

#define 

ID_ 

HINIBOTH 

57 

#define 

id] 

]hiniprivate 

58 

#define 

ID_ 

]data_heading 

59 

#define 

ID 

JESTJDATA 

60 

#define 

ID_ 

"initor 

61 

#define 

ID 

"location 

62 

#define 

id] 

]WRITE_ERROR 

63 

#define 

id' 

]delete_error 

64 

#define 

id] 

SAVEPOS_ERROR 

65 

#define 

ID 

QTEXT ERROR 

66 


ID_ADD 

10 


ID DISPLAY 

11 


IDDELETE 

12 


ID_SAVE 

13 


ID_EXIT 

14 


ID_FIRST_BUTTON 

ID_ 

ADD 

ID_LAST_BUTTON 

ID 

_EXIT 

NUM_BUTTONS 

5 


NUM MENUS 

4 
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#define 

ADD_MENU 

100 



#define 

DISPLAY_MENU 101 



#define 

DELETE_MENU 

102 



#define 

SAVE_MENU 

103 



#define 

EXIT_MENU 

104 



#define 

FIRST_MENU 

ADDJ 

MENU 


#define 

IDM_DISPLAY_ 

USER 

200 


#define 

IDM_DISPLAY_ 

SYS 

201 


#define 

IDM_DISPLAY_ 

JJSERSYS 

202 


#define 

IDM_DISPLAY_ 

"private 

203 


#define 

IDM_REFRESH 


204 


#define 

IDM_ABOUT 


205 


#define 

DISPLAY_FIRST 

IDM_ 

_DISPLAY_USER 

#define 

IDM_DELETE_APP 

300 


#define 

IDM_DELETE_KEY 

301 


#define 

IDM ADD APP 


400 


#define 

IDM_ADD_KEY 


401 


#define 

IDM_SAVE CHANGES 

500 


#define 

IDM_SAVE_LOCATION 

501 


#define 

MAX_TITLE 

1024 



#define 

MAX_BUFF 

128 



#define 

MAX_LINE 

16 



#define 

APP_LBOX 

1 



#define 

KEY_LB0X 

2 



#define 

DATA_WND 

3 



#define 

HEX_SIZE 

47 



#define 

HEX_START 

7 



#define 

ASCII_START 

HEX_START + 

HEX_SIZE + 1 


#define 

#define 

#define 

WM_UPDATE_DATA WM_USER + 1 

FIXED_FONT_LCID 5 

ADD_DLG 

1000 

#define 

DID_APP_NAME 

1001 

#define 

DID_KEY_NAME 

1002 

#define 

DID_KEY_DATA 

1003 

#define 

ABOUT_DLG 

2000 

#define 

WM_U P DAT E_TIT L E 

WM_USER 




void APIENTRY change_ini_file(USHORT); 

void APIENTRY cleanup(void); 

void APIENTRY create_controls(HWND); 

void APIENTRY enum_app_names(HINI,USHORT); 

void APIENTRY enum_key_name(PSZ); 

int APIENTRY format_line(PSZ,PSZ,int,int); 

void APIENTRY get_key_data(PSZ,PSZ); 

HPS APIENTRY init_data_window(HWND); 

int APIENTRY paint_data_window(HWND,HPS,int); 

USHORT APIENTRY post_error(HWND,USHORT); 

void APIENTRY process_command(HWND,MPARAM,MPARAM); 

void APIENTRY process__control(HWND,MPARAM,MPARAM) ; 

void APIENTRY refresh_display(void); 

void APIENTRY size_controls(MPARAM); 

INITOR.RC 

/* 

Initor Resource File 

*/ 

#include <os2.h> 

#include "initor.h" 

RCINCLUDE initor.dig 

ICON ID_APPNAME INITOR.ICO 

MENU ADD_MENU PRELOAD MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM "Add New Application", IDM_ADD_APP 
MENUITEM "Add New Key", IDM_ADD_KEY 

END 

MENU DISPLAY_MENU PRELOAD MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM "User Profile", IDM_DISPLAY_USER 

MENUITEM "System Profile", IDM_DISPLAY_SYS 

MENUITEM "User & System Profile", IDM_DISPLAY_USERSYS 
MENUITEM "Open Private...", IDM_DISPLAY_PRIVATE 

MENUITEM "Refresh", IDM_REFRESH 

MENUITEM "About Initor", IDM_ABOUT 

END 

MENU DELETE_MENU PRELOAD MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM "Delete Application Section", IDM_DELETE_APP 
MENUITEM "Delete Selected Key", IDM_DELETE_KEY 

END 


4 Ob 
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MENU SAVEJVIENU PRELOAD MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM "Changes", IDM_SAVEXCHANGES 

MENUITEM "Screen Location", IDM_SAVE^LOCATION 

END 


STRINGTABLE LOADONCALL MOVEABLE 

BEGIN 

ID_ADD 
ID_DISPLAY 
ID_DELETE 
ID_SAVE 
ID_EXIT 
ID_APPNAME 
ID_APPLICATION 
ID_KEY 
ID_DATA 

%4d ASCII Bytes" 

ID_HINIUSER 
ID_HINISYS 
ID_HINIBOTH 
ID_HINIPRIVATE 
ID_INITOR 
ID_LOCATION 
ID_WRITE_ERROR 
ID_DELETE_ERROR 
ID_SAVEPOS_ERROR 
ID_QTEXT_ERROR 

END 


"Add" 

"Display" 

"Delete" 

"Save" 

"Exit" 

"OS/2 INI File Editor" 
"Application Name" 

"Key Name" 

" Offset 


%4X Hex Bytes 


"Viewing User Profile" 

"Viewing System Profile" 

"Viewing User And System Profile" 

"Viewing %s" 

"INITOR" 

"SCREEN POS" 

"Update to initialization file failed" 
"Error deleting initialization file entry" 
"Unable to save current screen location" 
"Unable to retrieve key data text" 


INITOR.DLG 

DLGINCLUDE 1 "INITOR.H" 

DLGTEMPLATE ADD_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Add Section", ADD_DLG, 87, 61, 221, 116, FS_SCREENALIGN | 
WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR 

BEGIN 


LTEXT 

"Application Name:", 

, -1: 

, 6, 

105, 

00 

00 

LTEXT 

"Key Name:", -1, 6, 

CD 

81, 

8 


LTEXT 

"Key Data:", -1, 6, 

51, 

81, 

8 


ENTRYFIELD 

"", DID APP NAME, 7, 
WS_GR0UP 

, 93. 

, 206 

, 8, 

ES_MARGIN j 

ENTRYFIELD 

"", DID_KEY_NAME, 7, 

, 66, 

, 206 

, 8, 

ES_MARGIN 

MLE 

"", DID_KEY_DATA, 5, 

22, 

210 

, 25, 

, MLSJVORDWRAP 
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MLS_VSCROLL ] MLS_IGNORETAB 

DEFPUSHBUTTON "~0k", APP_LBOX, 49, 4, 40, 14, WS_DISABLED 
PUSHBUTTON 11 -Cancel' 1 , KEY_LB0X, 130, 4, 40, 14 

END 

END 

DLGTEMPLATE AB0UT_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "OS/2 Initialization File Editor", AB0UT_DLG, 83, 99, 268, 
49, 

FS_SCREENALIGN | WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR 

BEGIN 

LTEXT "Initor Version .5", 105, 96, 31, 72, 11 

LTEXT " Copyright Derrel Blain, Jeff English, 

Kurt Deli" 

"mon 1993", -1,7, 22, 255, 11 
PUSHBUTTON "Ok", APP_LBOX, 112, 5, 40, 14 

END 

END 


Using INITOR 

Looking at System Initialization Files 

The INITOR INI editor is fairly self-explanatory. Remember that INIs in OS/2 follow 
a three-tiered structure. Because the data has a three-tiered layout, the editor we create, 
called INITOR, is designed to display the application name, key name, and key data at 
the same time. For this, two list boxes and an application-defined data window are used 
as shown in Figure 8.2, INITOR’s application window. A row of buttons across the bottom 
of INITOR gives access to pop-up menus that display system or private INI files. These 
pop-up menus also enable you to add or delete entries in the open file. 

Add the editor’s icon to a window and open the application. Use the Display button 
at the bottom of the application’s main window to open the desired INI. This button 
will give you a number of choices both for system INIs and private INIs. As always, be¬ 
fore changing any file, especially a system file, ensure that you have a backup of that file 
in a safe place. 

List boxes are provided in which the three tiers are displayed. The Application Name 
area represents the highest level of organization. Every entry in this is displayed. The next 
level down is the Key Name window. The entries displayed in this area change depend¬ 
ing on which application name is highlighted. Every entry displayed in the Key Name 
area belongs to the highlighted application name. Spend some time clicking various ap¬ 
plication names to see the key names that may be associated with them. 
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Figure 8.2. 

INITOR’s application 
window. 



The most detailed area and the lowest in the hierarchy is in the Key Data window. 
This information may have a number of different formats depending on the application 
that placed the key data in the INI file. The INITOR application displays this data in 
both ASCII text and hexadecimal format. Once again, the data displayed in this area is 
the data associated with the entry highlighted in the previous level of the hierarchy. The 
data displayed will change depending on the Key Name that is highlighted. 

Use INITOR to display entries from the user profile and the system profile. Spend 
some time exploring these system INIs so that you can get a feel for the kind of entry 
they contain. Identify which entries are in the system INI file and which are in the user 
INI file. For example, the PM_SP00LER application name contains entries in both the system 
and user INI files. An application will typically need to query entries from one of the 
system initialization files. If, for example, your application displays dates, you may want 
to query the date separator character configured by the user. A user may change this set¬ 
ting by settings in the country portion of the system settings. The “PM_NationaT “sDate” 
application/key combination found in the OS2.INI file will provide you with this infor¬ 
mation. You may even use the INITOR to change some of your system’s settings, but 
wait until you are thoroughly familiar with the settings you are changing and their effect. 

The remaining features follow the customary editing techniques that you would ex¬ 
pect, with one important difference. The Save button also presents you with a choice to 
save the application’s screen location. This is included simply to enable you to see an 
application saving data into an INI, which is used by a later instance of the application. 
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Try moving the application far to one side of the screen, and then save its location. Click 
the Display button, and then click Refresh. Now, look for the INITOR entry in the User 
INI file. You may use the choices that appear with the Display button to choose the User 
INI file. 

This application is a completely functional editor, so take some care with the changes 
you make to the INIs that are on your system, because no undo is provided. 

Using Your Own INI File 

Although INITOR saves its initial screen location in a system INI file, an application 
should store its configuration information in a private INI file. Using a private INI file 
prevents the loss of settings if OS/2 is reinstalled or the system INI files are rebuilt by the 
user. Pressing Alt+Fl for 20 seconds before the first OS/2 Logo panel appears will reset 
the default desktop configuration. You will recall that before data may be written to a 
private INI file, it must be opened by using the Prf OpenProf ile function. If the 
file exists, it is opened; otherwise, a new file is created. An INI handle is returned if 
the function is successful, or NULL is returned if an error occurs. The PrfOpenProfile 
function requires an anchor block handle and a pointer to a null-terminated string that 
contains the filename: 

HINI hlni = PrfOpenProfile(hab,pFullFileName); 

When you select the Open Private menu item from the Display pop-up menu, 
INITOR invokes the common open file dialog (see Figure 8.3). You may then open or 
create any private INI file. Although most INIs use the INI file extension, it is not re¬ 
quired. The PrfOpenProfile function will fail if the current system or user INI names 
are specified. Attempting to open an INI created by Windows applications in a WIN/ 
OS2 session will also fail because these files are stored in different formats. 

After a private profile file is opened or created, it may be queried or written to by 
using the same API as the system INIs. However, when your application is through up¬ 
dating the file, it should be closed by using the Prf GloseProf ile function. This func¬ 
tion takes the INI file handle returned from a Prf OpenProf ile call as its only param¬ 
eter. This function may not be used to close one of the system INIs. If successful, the 
function returns TRUE, or it returns FALSE if an error occurs. 

When OS/2 is first installed, the system INI files are built by the MAKE.INI pro¬ 
gram from the INI.RC and INISYS.RC files found in the \OS2 directory. You may use 
this program to create new system INI files or a default INI file for your application. The 
input file is a standard PM resource script file where the entries are defined through string 
tables. 
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Figure 8.3. 
Common open 
file dialog. 
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Spooler Functions—Additional Profile API 

Applications written for OS/2 1.x were required to query the system INI files to retrieve 
information about the installed printers. This required intimate knowledge about how 
the data was stored in the INI files. When retrieved, the data had to be parsed before 
being used to open a device context with a printer driver. Although the information about 
printer and queue configurations is still stored in the system INI files in OS/2 2.1, a new 
group of functions have been added to insulate applications from knowing the details 
about how the data is stored. The Spooler API provides the following three functions for 
getting information on the configuration of the print subsystem: 

SplEnumQueue Enumerates queues on the local workstation. 

SplQueryQueue Returns information about a print queue and 

jobs in it. 

SplQueryDevice Returns information about a print device. 

The SplEnumQueue will return a list of the print queues on a local or remote work 
station. The second parameter enables you to specify the level of detail required. By call- 
ing the function with ulLevel set to the desired information level and the p Buffer field 
set to NULL, the amount of storage space required may be determined: 

SplEnumQueue (pszComputer,ulLevel,pBuffer,ulBuffSize,pcReturned, 
pcTotal,pcbNeeded,pReserved) 
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PSZ pszComputer Pointer to a null-terminated string that 

identifies the name of computer to enumerate 
queues from. A NULL string indicates that 
the local workstation should be enumerated. 
ULONG ulLevel Specifies the level of detail required. pBuffer 

will contain the following: 

O An array of PRQINF03 structures. Included in the PRQINF03 structure are the 
queue name, description, priority, and type. 

# An array of PRQINF03 structures with each one followed by zero or more 
PRJINF02 structures. The total number of PRQINF03 structures will be returned 
inpcReturned. The cJobs field of the PRQINF03 structure will indicate the 
number of PRJINF02 structures that follow. The PRJINF02 structure contains 
information on print jobs currently in the queue. Included in this information 
are the job’s ID number, priority, position in the queue, and size. 

# A null-terminated queue name string. 

# An array of PRQINF06 structures. The PRQINF06 structure contains the same 
fields that the PRQINF03 structure does, plus pointers to null-terminated strings 
that identify a remote computer name and a remote printer name. 

PVOID pBuffer Pointer to the location return data is to be 

copied. Setting this field to NULL will cause 
the pcbNeeded to contain the memory 
required to hold the data for the requested 


ULONG 

ulBuffSize 

information level. 

Length in bytes of the memory pointed to by 

PULONG 

pcReturned 

pBuffer. 

Number of entries returned. 

PULONG 

pcTotal 

Total number of entries available. 

PULONG 

pcbNeeded 

Size in bytes of available information. A value 

PVOID 

p Reserved 

of 0 specifies that the size is not known. 
Reserved parameter, must be NULL. 


The SplQueryQueue will return information about a specific print queue including 
any print jobs in it. The parameters to this function are similar to the SplEnumQueue 
function described previously. You can use this function in your application to track the 
status of a print job once submitted. By setting a timer and requesting level 4 informa¬ 
tion from the SplQueryQueue, the status of the print job, including position in the queue 
and job priority, maybe displayed in astatus line. The SplQueryQueue is defined as follows: 

SplQueryQueue(pszComputer,pszQueueName, 

ulLevel,pBuffer,ulBuffSize,pcbNeeded) 
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Pointer to a null-terminated string that 
identifies queue to return information on. 

The pszName field from the PRQINF03 or 
PRQINF06 should be used to provide this 
value. 

As with the SplEnumQueue function, the memory required to hold the requested 
information may be determined by calling the function with the desired ulLevel and a 
NULL pBuf f er. The bytes required will be returned in pcbNeeded. 

If required, the SplQueryDevice function will return information about a device 
or port: 

SplQueryDevice (pszComputer,pszPrintDevice, 


ulLevel,pBuffer,ulBuffSize,pcbNeeded) 


PSZ 

pszPrintDevice 

Pointer to a null-terminated string that is 
either the name of print device or port to 
query. ulLevel 0 requires a port name. Valid 
port names may be enumerated from the 
PM_SPOOLER_PORT application section 
of the system INI file. Level 1 is undefined 
and level 2 or 3 require a print device name. 

ULONG 

ulLevel 

Level of detail required. 

0 

pszPrintDevice 

Pointer to a null-terminated string that 
indicates the port name to query. 

2 

pszPrintDevice 

Pointer to a null-terminated string that 
indicates the print device to query. 

3 

pBuffer 

Contains pointer PRDINF03 structure. 
Included in PRDINF03 structure are the 
time spent printing, the job ID, and the 
device timeout. 

PVOID 

p Buffer 

Pointer to the location return data is to be 
copied. 

ULONG 

ulBuffSize 

Length in bytes of the memory pointed to by 
pBuffer. 

PULONG 

pcbNeeded 

Size in bytes of available information. 


The following is a quick summary of important additional entries that may be in 
system INI files. 
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PSZ pszQueueName 




Real-World Programming for 


HINIJUSERPROFILE 
PM_DEVICE_D RIVERS 

PM_Fonts 


PM_Font_Drivers 

PM_Nationai 

PM_SPOOLER 

QUEUE 


OS/2 2.1 


This entry identifies the drivers installed on 
your system. The key data consists of the 
name of your device driver file without the 
extension, and the key data is the fully 
qualified pathname of the driver filename. 

Your applications may include Type 1 fonts 
that can be installed on the PM desktop. 
Although these fonts may be installed by 
using a font palette, requiring a user to do this 
is undesirable. Those fonts may be installed 
by adding entries to this section where the key 
name is the filename of the .ATM file and the 
data is the fully qualified pathname of the 
filename of the AFM file. Fonts in this section 
are public and are read by PM at system start¬ 
up. To make the fonts available without 
restarting, call GpiLoadPublicFonts for each 
facename contained in the font file added to 
the INI file. 

The key name entry is the name of a DLL 
that conforms to IFI (intelligent font inter¬ 
face) specification. The data is the fully 
qualified pathname to the DLL. The default 
entry describes the PMATM DLL supplied as 
part of OS/2 2.1. 

This application section contains various 
country specific settings for the display of 
dates, time, and monetary values. 

This entry contains the default queue name. 

If you have more than one printer installed on 
your machine, you may change this value by 
selecting the Set Default menu item of any 
print object. Applications are not informed of 
changes to this value, so you must select the 
Refresh option from the Display menu in 
INITOR to see the change. 
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PRINTER 


SYS_DLLS 

LoadOneTime 


LoadOncePerProcess 


HINLSYSTEMPROFILE 

PM_SPOOLER_PRINTER 


In releases of OS/2, prior to 2.1, this con¬ 
tained the default printer. In 2.1, it remains 
for compatibility with 1 .X applications and 
will contain the same value as the QUEUE 
keyname described previously. 

This item contains the name of a DLL that is 
loaded at system start-up. The default is the 
single entry REXXINIT. Additional DLLs 
may be added by appending a comma 
followed by the DLL name. Each time the 
system is started, the initialization code for 
this DLL will be called. Changing this item is 
considered risky because a failure in the 
initialization of the DLL being added may 
prevent OS/2 from booting successfully. 

This item contains the name of a DLL that is 
loaded at the start-up of each process. The 
default is the single entry PMCTLS. Addi¬ 
tional DLLs may be added by appending a 
comma followed by the DLL name. 

This application section contains entries for 
installed printer drivers. 


The keyname is the physical device name, and the data string is defined as follows: 
<addr>;<ddl>;<ql>;<netopt>;<timeout>; 

ex. LPT 1;PSCRIPT.HP LaserJet IHSi PS v52_3;HPLaserJ;;45; 


<addr> 

Address (ex. LPTn, COMn, IEEEn), which 
can be NULL (that is, not connected). 

<ddl> 

List of device drivers defined for the printer 
(comma between each name), which can be 
null. The first one is taken as the default. 

<ql> 

List of queues defined for the printer. 

<netopt> 

Network printer options, which may be 
omitted. 

<timeout> 

Timeout value in seconds. 
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PM_SPOOLER_PRINTER_DESCR 
PM_SPOOLER_QUEUE 
PM_SPOOLER_QUEUE_DD 
PM_SPOOLER_QUEUE_DESCR 
INI.RC and INISYS.RC files 

Chapter 11, “Printing,” discusses the Spooler API in greater detail. Further, it out¬ 
lines the conversion of profile queries to the appropriate spooler function. 
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The Memory Architecture of OS/2 2.1 

Many developers starting out programming for OS/2 2.1 have programmed for DOS. 
The clunky, segmented addressing architecture demanded by the chips on which DOS 
runs is notorious for its inefficiency and quirkiness. A 64OK limitation and competing 
and confusing schemes such as extended and expanded memory are the result of this seg¬ 
mented architecture. OS/2 2.1, running on the 80386 chip, is capable of 
leaving all this behind. 
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OS/2 2.1 has a linear address space. That is, the address of each byte that follows 
another is incremented by one. Some call this a “flat address space.” Memory allocation 
in OS/2 2.1 takes advantage of the 32-bit protected mode of the Intel 80386 and 80486 
processors. Because OS/2 2.1, as of this writing, runs on a chip that uses 32-bit pointers, 
4GB of memory may be addressed. Not all this memory, however, is immediately avail¬ 
able to an application, nor is the memory architecture as simple as the term “flat address 
space” implies. 

Remember, OS/2 2.1 is a true multitasking operating system. This means that a 
number of different processes, which may have any number of threads, occupy the sys¬ 
tem memory simultaneously along with the operating system. If any process could access 
any place in memory at will, confusion and corruption would often be the result. Fur¬ 
ther, if the physical address space taken by one application was large, it might limit an¬ 
other from running. More often than not this would be the case because although memory 
is cheap, it’s not yet free. Most systems do not have 4GB laying about for use. Most of¬ 
fice and home systems have 8 physical megabytes available to the CPU, so some mecha¬ 
nism is necessary to allow applications to use a much larger virtual address space. 

In OS/2 2.1, each process can access 512M of linear address space. This area of memory 
is referred to as the process address space. The 512M limit is incurred by the need to 
support both 16-bit and 32-bit applications. This 512M of potential memory is, in fact, 
further limited to the amount of physical memory added to the amount of available hard 
disk memory. 

To make this large address space available to multiple applications in the much smaller 
space of physical memory available on most machines, OS/2 2.1 uses a paged memory 
system. This 512M of memory for each process is completely unrelated to the 512M 
available to other processes that may be running on the machine. The total amount of 
committed memory for all processes, however, cannot exceed the amount of physical 
memory plus the available hard disk space. 

The entire 4GB of address space is partitioned into private, shared, and system 
memory. Figure 9.1 illustrates how the address space is allocated to these three regions. 

Of the 64M reserved for private memory allocation, the first 64K is reserved for 
operating system overhead. The address range from 448M to 512M is reserved for shared 
memory. Addresses above 312M are in the OS/2 system space; these are where the oper¬ 
ating system kernel is loaded. The remaining 384M between addresses 64M and 448M 
is allocated as needed for either private or shared memory. 
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Figure 9.1. 

OS/2 address space. 
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Private memory for each process grows upward (upward in value) from the bottom 
64K. This is true for every process running on the system. Shared memory starts at the 
top of the 512M address space and grows downward. Shared memory is memory shared 
across processes. Keep in mind that a process is different from a thread. A process may 
have many threads, but processes are individuals to themselves. Shared memory is used 
to share memory across processes as well as for Dynamic Link Library (DLL) code and 
data. Private memory is composed of the application’s code, data, heap, stack, and allo¬ 
cated non-shared memory objects. 

Shared memory is allocated for all processes. For example, if several processes are 
running and one allocates 2M of shared memory, this shared memory is allocated from 
the shared memory address space for all the processes. This is true even if some of the 
processes do not have access to the allocated memory. 

16-Bit and 32-Bit Memory 

To fully understand the allocation scheme, you will find it helpful to first understand 
the 16-bit segmented allocation scheme. Prior versions of OS/2 relied on the seg¬ 
mented memory model, and all memory was addressed by a 16-bit selector and 16-bit 
offset. Memory was allocated by blocks of up to 64K, and a 16-bit segment selector was 
returned. Memory was then accessed by combining the 16-bit selector with a 16-bit off¬ 
set, with all offsets starting at 0. Memory was allocated and accessible immediately after 
allocation. This architecture limits each segment to 64K, so allocating blocks larger than 
64K required the segment register to be changed to match the desired portion of allo¬ 
cated memory. 
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OS/2 2.1 provides support for true 32-bit memory allocation and access, but it also 
still supports 16-bit segmented memory allocation for 16-bit applications. As it is pos¬ 
sible for 32-bit applications and 16-bit applications to share data address spaces (shared 
memory) and also to pass memory addresses between each other, it is necessary to allow 
for differences in the addressing scheme. This support is provided by placing several re¬ 
strictions on the 32-bit memory allocation process. 

In the 32-bit world, all addresses are near addresses into what is called the FLAT address 
space. The FLAT address space, sometimes called linear address space, is the entire 4GB 
of addressable memory. Because the 16-bit world requires all segment offsets to start at 
0, you can see that only those addresses in the 32-bit space which have 0 as the low word 
of their address should map to segment boundaries. This is done in OS/2 by what is called 
memory tiling, or TILED memory, which restricts the base linear addresses to multiples 
of 64K. Figure 9.2 shows how the two addressing schemes can share the same memory 
space through tiling. 


Figure 9.2. 
Tiled memory 
architecture. 
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Notice that all selectors have the low 3-bits set and that the memory referenced starts 
on a 64K multiple. Because the system reserves the first 64K, it is never possible to have 
a selector value of 0. The process of converting linear addresses to a 16-bit selector and 
offset and vice versa will be covered in Chapter 13, Calling 16-Bit Code, which dis¬ 
cusses the concept of thunking. 

OS/2 2.1 enables you to force memory allocation to follow the TILED memory 
restriction when memory is allocated. Using this option does reduce the amount of 
available memory address space because the entire range of 64K is reserved on such an 
allocation request. This is discussed later when we get into the memory management API. 
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32-Bit Memory 

The fundamental unit of memory for OS/2 2.1 memory management is the page. A page 
of memory is always 4,096 bytes, 4K. If an application needs to allocate only 64 bytes of 
memory, this still causes a whole page, 4,096, to be allocated to contain that 64 bytes. If 
more than a page of memory is asked for, a page range is allocated. A page range is several 
contiguous pages. 

The total virtual memory space available to a process is divided into pages. Each of 
these pages may be in one of only three states at any particular moment. These three states 
are as follows: 

Free The page has not been allocated. 

Private The process has allocated the page for use. 

Shared The page has been allocated as memory to be shared between 

processes. 

Memory pages have an additional pair of characteristics. A memory page may be 
committed or uncommitted. Committed pages within memory objects have been allot¬ 
ted physical storage for the logical address range. Uncommitted pages are not yet backed 
by physical storage. 

Memory allocation merely reserves a range of memory addresses in the process ad¬ 
dress space. It does not use any physical memory until the memory is committed and 
referenced. Memory commitment is the process of physically allocating memory from 
the system and assigning it to the address space that has been allocated. Requests to com¬ 
mit memory are done on a page basis. A page in memory cannot be accessed until the 
page has been committed. Attempts to access uncommitted memory will result in a pro¬ 
tection violation. 

Memory objects are allocated in units of 4K pages. All memory requests are resolved 
to a page boundary. All pages allocated are fully addressable. A request to allocate 1 byte 
of memory will result in a 4K page being allocated. The entire 4K is available for use by 
the application. A request to allocate 4,097 bytes of memory will result in two 4K pages 
being allocated. Again, the entire 8K is available for allocation. For small memory re¬ 
quests, this can result in a lot of unused memory being allocated, thus reducing the amount 
of memory available for use. We will discuss ways to handle such requests more efficiently 
later in this chapter. 

When an application no longer requires the use of a physical memory object, it can 
either be freed or decommitted. Decommitment allows the application to commit the 
memory again without the need for a memory allocation request. 
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Notice that applications do not actually allocate “pages” for their use. Applications 
or processes allocate memory, which is then set aside by the operating system in terms of 
pages. Applications allocate and use memory as memory objects. Memory objects are one 
or more pages. Processes or applications may allocate more than one memory object. These 
memory objects have the following characteristics: 

# Each is allocated in increments of 4K. 

# Each has memory objects that are not relocatable. 

The operating system reserves a linear address range when an application asks it to 
allocate memory. This address range, however, is not backed by physical memory until 
the memory is committed. Any attempt to use uncommitted memory will cause an ac¬ 
cess violation. 

Memory may be committed when it is allocated, or it may be allocated as uncom¬ 
mitted and then committed at a later time. If the memory is committed when allocated, 
all of it is committed, and it is available for immediate use. If the memory is allocated as 
uncommitted, however, individual portions of the memory may be allocated at different 
times later. Allocated memory objects that are not committed are called by the peculiar 
term “sparse.” 

You can see that the best practice for memory management is to allocate a sparse 
memory object initially for as much space as the process might need. Later, parts of the 
memory object may be committed as needed. When a memory object is allocated as 
uncommitted, no physical memory is involved, so it is not wasteful to allocate several 
extra megabytes. Better yet, this practice actually optimizes the use of memory within 
the system. Pages are not given memory storage to back them up until they are both 
committed and referenced. No memory is wasted for unreferenced, committed pages. 

Access to committed pages is further refined to have access rights: read, write, or ex¬ 
ecute. A fourth right, guard page, is also available but is not discussed here. 

At any time, an application may change the access rights of a committed page of 
memory. It may also commit and decommit allocated pages on demand. Figure 9.3 shows 
an initial allocation request for 16K of memory. 

Notice that an entire range of 64K of address space has been allocated. This is due to 
the current implementation of memory allocation in OS/2 2.1, which makes all memory 
allocation requests follow the TILED memory scheme. 

Before accessing any of this memory, the application would have to make a request 
to commit the necessary pages. Figure 9.4 shows the result of a request by an application 
to commit the first 8K of memory, starting at address 14F00000. 
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Figure 9.3. 

16K uncommitted 
memory allocation. 


Figure 9.4. 

Memory committment. 
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At this point, we are free to access memory in the range 14F00000 to 14F01FFF. 
Attempts to address 14F02000 would generate a protection violation. 

Memory objects cannot be resized after allocation. An application, thus, must allo¬ 
cate the maximum amount of memory for a memory object and commit the memory as 
needed. 

Committing and decommitting pages in a range of allocated memory as they are 
needed is a more efficient way of managing memory than requesting memory allocation 
and commitment every time. This, however, requires the application to keep track of 
how many pages have been committed so that memory requests to commit and decommit 
do not fail. 

An easier way of handling such a situation is to allocate a memory object as a heap 
and use the memory suballocation functions to allocate and commit the memory as needed. 
The heap management functions in the operating system keep track of the committed 
and uncommitted pages and manage these pages as memory requests are made. Care must 
be taken when using a heap, as accessing memory above the requested amount of 
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suballocated memory may write over memory allocated to another suballocated block of 
memory or destroy information maintained by the heap itself. Memory requests 
suballocated from a heap are rounded up to a multiple of 8 bytes. 

The Memory Manager API 

The memory management functions in OS/2 are divided into three categories: nonshared, 
suballocated, and shared. Some functions that are discussed as a part of the nonshared 
memory API are also available for use with shared memory. 

NonShared Memory 

NonShared memory is allocated with the DosAllocMem API: 

APIRET DosAllocMem (PPVOID ppBaseAddress, ULONG ulObjectSize, 

ULONG ulAllocationFlags) 


PPVOID 

ppBaseAddress 

Address of pointer to 
receive memory address. 

ULONG 

ulObjectSize 

Maximum size of 
memory object to be 
allocated. 

ULONG 

ulAllocationFlags 

Memory allocation flags: 


PAGJRJEAD 

Allows read access. 


PAG_EXECUTE 

Allows execute access 
(executable code). 


PAG.WRITE 

Allows write access 
(includes read and 
execute access). 


PAG_COMMIT 

Commits all requested 
pages. 


OBJLTILE 

Allocates memory on a 
64K boundary. 


The following example allocates an 8K memory object: 

PBYTE pMem; 

APIRET RetCode; 

RetCode = DosAllocMem ((PPVOID) &pMem, 8192L, PAG_READ j PAG_WRITE); 

The memory object returned in pMem must be committed before it can be accessed. 
Memory can be committed at the same time it is allocated by using the PAG_COMMIT flag: 

RetCode = DosAllocMem ((PPVOID) &pMem, 8192L, 

PAG_READ | PAGJVRITE | PAG_COMMIT); 

426 



Chapter y Memory Management 


The memory object returned in pMem can now be immediately accessed. Each page 
of a memory object is initialized to zeroes the first time the page is read or written. The 
flag f ALLOC can be used to request memory that is readable, writable, and committed: 

#define fPERM (PAG_EXECUTE + PAG_READ + PAGJVRITE) 

#define fALLOC (0BJ_TILE + PAG_COMMIT + fPERM) 


Note: The current implementation of OS/2 2.1 always allocates memory as though 
the OBJ_TILE flag is set. If the PAG_COMMIT flag is set, however, only those pages 
required to satisfy the allocation request are committed. In the previous example, 
only the first four pages (8,192 bytes) would be committed, although 16 pages 
(64K) are allocated. This may change in a future release of OS/2 2.1. 

After the memory is allocated, it can be committed and decommitted as needed with 
the DosSetMem API: 

APIRET DosSetMem (PVOID pBaseAddress, ULONG ulRegionSize, 

ULONG ulAttributeFlags) 

PVOID pBaseAddress Base address of memory 

object. 

ULONG ulRegionSize Size of memory to set. 

ULONG ulAttributeFlags Memory attribute flags: 

PAG_COMMIT Commits pages specified 

in ulRegionSize. 

PAG_DECOMMIT Decommits pages 

specified in ulRegionSize 
starting at pBaseAddress. 
PAG_READ Read access. 

PAG_EXECUTE Execute access. 

PAG_WRITE Write access. 

PAG_DEFAULT Use default access. 

If you are committing memory, you must also specify PAG_DE FAULT or at least one of 
these—PAG_READ, PAG_WRITE, or PAG_EXECUTE. PAG_DEFAULT sets the access rights of 
the page to the same rights as when the memory object was allocated. 

The following example allocates an 8K memory object and commits the first page of 
the object: 

PBYTE pMem; 

APIRET RetCode; 

if ( !(RetCode = DosAllocMem ((PPVOID) &pMem, 8192L, 

PAG_READ | PAGJVRITE)) ) 
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{ 

} 


RetCode = DosSetMem ((PVOID) pMem, 4096L, 

PAG_COMMIT | PAG_READ | PAG_WRITE); 


Attempts to set the commitment state of a page of memory to a state it is already in 
will fail. The second call to DosSetMem in the following sequence will fail as the second 
page is already committed: 

RetCode = DosSetMem ((PVOID) pMem, 8192L, 

PAG_COMMIT | PAG_READ | PAG_WRITE); 

RetCode = DosSetMem ((PVOID) pMem+4096, 4096L, 

PAG_COMMIT | PAG_READ | PAG_WRITE); 

DosSetMem can also be used to change the access rights of committed pages of the 
memory object. The following example allocates and commits an 8K memory object 
and then changes the access right of the first page from readable and writable to only 
readable: 

PBYTE pMem; 

APIRET RetCode; 

if ( !(RetCode = DosAllocMem ((PPVOID) &pMem, 8192L, fALLOC)) ) 

{ 

RetCode = DosSetMem ((PVOID) pMem, 4096L, PAG_READ); 

} 

The first page is now readable, but the second page is still readable and writable. It is 
not possible to change the access rights for uncommitted memory. 

It is important for you to remember that the access right of PAG_EXECUTE can be set 
for a page of memory only if the memory was originally allocated with PAG_EXECUTE. 

When memory is no longer needed, you can release it with the DosFreeMem API: 

APIRET DosFreeMem (PVOID pBaseAddress) 

PVOID pBaseAddress Base address of memory object 

The following example allocates and commits an 8K memory object and then re¬ 
leases it when done: 

PBYTE pMem; 

APIRET RetCode; 

if ( !(RetCode = DosAllocMem ((PPVOID) &pMem, 8192L, fALLOC)) ) 

{ 


RetCode = DosFreeMem ((PVOID) pMem); 

} 



Chapter y Memory Management 


Any range of memory can be queried to determine its current state with the 
DosQueryMem API: 

APIRET DosQueryMem (PVOID pBaseAddress, PULONG pulRegionSize, 

PULONG pulAllocationFlags) 

PPVOID ppBaseAddress Base address of memory object. 

PULONG pulRegionSize Address of variable to receive region size. 

PULONG pulAllocationFlags Address of variable to receive allocation 

flags. 

DosQueryMem will scan the pages of memory starting at pBaseAddress and will re¬ 
turn the allocation flags of the memory in the range specified. On input, pulRegionSize 
points to a variable containing the size, in bytes, of the amount of memory to scan. The 
range of memory pages scanned will stop when a page with attribute flags different from 
the first page is encountered, the number of pages requested is scanned, or the end of the 
allocated object is reached. On return, the variable pointed to by pulRegionSize will 
contain the actual number of bytes scanned. 

The allocation flags include two new flags: 

PAG_FREE The memory pages are not allocated. 

PAG_BASE The first page specified is the first page of the allocated 
memory object. 

PAG_SHARED The memory pages are in a shared memory object. (This flag 
is returned only if the pages are committed.) 

The following example queries the second page to see whether it is committed and 
writable: 


ULONG ulMemSize = 4096L; 


ULONG ulFlags; 

if ( !(RetCode = DosQueryMem ((PVOID) (pMem+4096) 
&ulMemSize, &ulFlags)) ) 


{ 


if ( (ulFlags & (PAG_COMMIT 
(PAG_COMMIT 


{ 


| PAG_WRITE)) == 
| PAGJVRITE)) ) 


} 

} 

If every page of an allocated memory object has the same attributes, you can deter¬ 
mine the amount of committed memory for the object with the following call: 
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ULONG ulMemSize = OxFFFFFFFF; 

ULONG ulFlags; 

if ( (RetCode = DosQueryMem (pMem, &ulMemSize, &ulFlags)) || 

!(UlFlags & PAG_COMMIT) ) 
ulMemSize = 0L; 

This example requests DosQueryMem to scan all memory pages starting at pMem. If 
DosQueryMem returns successful, we still need to check the flags because all memory may 
be uncommitted. The applications presented later demonstrate how to determine the 
amount of allocated and committed memory when all pages do not have the same 
attributes. 

Suballocated Memory 

There are several drawbacks to allocating, committing, and managing the pages of memory 
that your application may need. 

• Your application must track which pages have been committed and must check 
this before each memory access. 

$ Small memory requests result in large amounts of address space being reserved. 

• Small memory requests for committed pages result in at least 4K of physical 
memory being used. 

% Memory allocation requests for new blocks of memory will be slower than 
suballocating from already committed memory. 

Consider the following memory requests: 

DosAllocMem ((PPVOID) &pMem, 20L, fALLOC); 

DosAllocMem ((PPVOID) &pMem, 32L, fALLOC); 

This results in a total of 128K of address space being reserved (64K for each request) 
and 8K of physical memory being used (4K for each request). It would be more efficient 
if we could satisfy both requests in a single page of committed memory. This is made 
possible by using the heap management functions of OS/2. In using a heap, you allocate 
a block of memory and indicate to OS/2 that the block is to be managed as a heap. OS/ 
2 will then satisfy memory requests from this heap by suballocating portions of this 
memory and returning the address to the application. OS/2 takes care of making sure the 
pages of memory are committed as necessary and of freeing them as they become avail¬ 
able. Your application should never call DosSetMem to change any attribute of the memory 
used for suballocation, as this will cause unpredictable results. As an alternative, it is also 
possible for your application to commit the pages of the heap and avoid having the heap 
functions do any memory commitment. 
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The first step in using memory suballocation (heaps) is to allocate a block of memory 
for this purpose. This is done by using the DosAllocMem function. This allocated memory 
is initialized for memory suballocation with the DosSubSetMem API, as follows: 


APIRET DosSubSetMem (PVOID pOffset, ULONG ulFlags, ULONG ulSize) 


PVOID 

pOffset 


Base address of memory 
object. 

ULONG 

ulFlags 


Memory suballocation 
flags: 



DOSSUBJNIT 

Initializes the memory 
for suballocation. 



DOSSUB_SPARSE_OBJ 

Tells OS/2 to manage 
the commitment of the 




pages. 



DOSSUB_GROW 

Increases the size of the 
memory used for 
suballocation. 



DOSSUB_SERIALIZE 

More than one process 
will be suballocating 
memory from this block 
of memory. 


The suballocation management for the heap uses 64 bytes of this memory to main¬ 
tain control information. In addition, all suballocation requests are satisfied in multiples 
of 8 bytes. The minimum size that can be set, thus, is 72 bytes. 

The DOSSUB_INIT flag is specified on the first call to DosSubSetMem so that the con¬ 
trol information for the heap can be initialized. 


Specify the DOSSUB_SPARSE_OBJ flag if you want OS/2 to manage the commitment 
of the pages. All pages in the range specified must be initially uncommitted. If the 
D0SSUB_SPARSE_0BJ flag is not set, all pages in the range specified must be committed 
before the call to DosSubSetMem. Because the heap must be updated as memory is 
suballocated, all pages must have minimum access rights of PAG_READ and PAG_WRITE. 

The following example allocates 64K for use as a heap and initializes it such that 
OS/2 will manage the commitment of pages: 


if 

{ 

} 


( !(RetCode = DosAllocMem ((PPVOID) &pMem, 0x10000, 
PAG_READ | PAGJVRITE)) ) 

RetCode = DosSubSetMem (pMem, 

DOSSUB_INIT | DOSSUB_SPARSE_OBJ, 0x10000); 




Real-World Programming for KJOi JL 2.1 


The DOSSUB_GROW flag can be used to increase the amount of memory available for 
suballocation. When using this flag, the setting of the DOSSUB_SPARSE_OBJ flag must 
match the setting that was used on the initial call to DosSubSetMem. The DOSSUB_INIT 
flag is ignored if DOSSUB_GROW is specified. This example allocates 128K for use as a heap, 
but only initializes the heap to use the first 64K. 


if ( !(RetCode = DosAllocMem ((PPVOID) &pMem, 0x20000, 
PAG_READ | PAGJVRITE)) ) 


{ 


RetCode = DosSubSetMem ((PVOID) pMem, 

DOSSUB_INIT | DOSSUB_SPARSE_OBJ, 0x10000); 


} 


Later, the range of memory used for the heap can be increased by calling DosSubSetMem 
as follows: 


RetCode = DosSubSetMem (pMem, 

D0SSUB_GR0W J DOSSUB_SPARSE_OBJ, 0x20000); 

Notice that the base address used in the second call to DosSubSetMem must match 
that used in the first call. 

If more than one process is going to perform memory suballocation from the same 
heap, it is necessary to specify the DOSSUB_SERIALIZE flag. Because OS/2 is a multitasking 
system, the system can interrupt one process, which could be in the middle of the code 
that is suballocating memory from the heap, to allow another process to continue and 
possibly call to have memory suballocated from the same heap. Because the first process 
may be in the middle of making updates to the control information for the heap and the 
second process may make updates as well, when the first process continues, the control 
information may be corrupted. Because the heap is then in a corrupted state, either the 
request to suballocate memory will never return or both processes will eventually cause a 
protection violation. By specifying the DOSSUB_SERIALIZE flag, OS/2 creates a sema¬ 
phore for the heap and every request to suballocate or free memory from the heap starts 
with a request to gain access to the semaphore and releases it when it is done. This pre¬ 
vents more than one process from executing within the heap management code at the 
same time. 

The first process to create the heap must allocate the memory as shared memory (dis¬ 
cussed later) and must use the DOSSUB_INIT and DOSSUB_SERIALIZE flags. Other pro¬ 
cesses that want to share the heap must specify the DOSSUB_SERIALIZE flags without the 
DOSSUB_INIT flag. We will use this in an example later when we discuss shared memory. 

When the heap has been initialized for suballocation, we can use the DosSubAllocMem 
API to request memory: 
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APIRET DosSubAllocMem (PVOID pOffset, PPVOID ppBlockOffset, 

ULONG ulSize) 

PVOID pOfFset Base address of the heap. 

PPVOID ppBlockOffset Address of pointer to receive memory address. 
ULONG ulSize Amount of memory for use by the heap. 

All memory requests are rounded up to the next multiple of 8 bytes. The following 
example requests 22 bytes from the heap allocated previously: 

PBYTE pSubMem; 

APIRET RetCode; 

RetCode = DosSubAllocMem (pMem, (PPVOID) &pSubMem, 22); 

When the suballocate memory is no longer needed, you can release it with the 
DosSubFreeMem API: 

APIRET DosSubFreeMem (PVOID pMem, PVOID pBlockOffset, ULONG ulSize) 

PVOID pMem Base address of the heap. 

PVOID pBlockOffset Address of pointer to receive memory address. 

ULONG ulSize Size of memory to suballocate. 

The amount of memory specified in ulSize will be rounded up to the next multiple 
of 8 bytes and, after rounding, must match the amount actually suballocated. The fol¬ 
lowing example frees the memory requested in the previous example: 

RetCode = DosSubFreeMem (pMem, pSubMem, 24); 

When you are done with the heap, you must call the DosSubUnsetMem API to enable 
OS/2 to free the resources it has allocated to manage the heap: 

APIRET DosSubUnsetMem (PVOID pMem) 

PVOID pMem Base address of the heap. 

All calls to DosSubSetMem must be matched with an equivalent call to 
DosSubUnsetMem. The memory used by the heap can then be freed with a call to 
DosFreeMem after DosSubUnsetMem has been called. The following example ends the use 
of the heap and frees the memory we allocated earlier: 

if ( '(RetCode = DosSubUnsetMem ((PVOID) pMem)) ) 

{ 

RetCode = DosFreeMem ((PVOID) pMem); 

} 
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Shared Memory 

Until now we have talked about memory allocated for the private use of a process. Shared 
memory is memory that can be addressed by multiple processes. Shared memory is used 
when two or more processes need to share data or when data is copied to or from the 
OS/2 clipboard. While memory is allocated from the shared memory arena and the ad¬ 
dress space is reserved in the process address space of all processes, a process must explic¬ 
itly gain access to the memory in order to access it. 

Once access to shared memory is obtained, the processes must coordinate among 
themselves whenever the memory is updated. This is usually done using semaphores. No 
coordination is required when just reading the shared memory. 

Shared memory is initially allocated by one process. So how do other applications 
know the address of the shared memory in order to access it? There are two methods for 
doing this. The first is to use named shared memory. In this case, shared memory is allo¬ 
cated, and a unique name is assigned to the memory. At that point, any application know¬ 
ing the name of this memory can access it by referring to the same name. The second 
method is to use unnamed shared memory. In this case, shared memory is allocated, and 
the address of this memory is passed to the other applications. At that point, the other 
processes can access the memory. It is also possible for a process with access to a shared 
memory object to give access to another process. 

When each process with access to shared memory is finished using the memory, each 
process must free the shared memory. This is because the shared memory object main¬ 
tains a count of the number of processes that have gained access to it, and the physical 
memory assigned to the shared memory object is not freed until all processes using the 
memory have freed it. Failure of each process to free the shared memory will result in 
reducing the address space available for shared memory. 

Shared memory is allocated by using the DosAllocSharedMem API: 

APIRET APIENTRY DosAllocSharedMem (PPVOID ppb, PSZ pszName, 

ULONG cb, ULONG flag) 

PPVOID ppb 

PSZ pszName 


Address of pointer variable 
to receive the memory 
address. 

Name of the named shared 
memory object. This name 
has the form 

\SHAREMEM\name. name 
can be any name that meets 
the criteria for a valid OS/2 
filename. 
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Maximum size of the 
memory object to be 
allocated. 

Memory allocation flags: 

PAG_READ Allows read access. 

PAG_EXECUTE Allows execute access 

(executable code). 

PAG_WRITE Allows write access (includes 

read and execute access). 

PAG_COMMIT Commit pages when 

allocated. 

OBJ_TILE Allocate on 64K boundary. 

OBJLGETTABLE Memory is gettable by other 

processes. 

OBJ_GIVEABLE Memory is giveable to other 

processes. 

This function operates the same way as the DosAllocMem API, except that memory 
is allocated from the shared address space and there are some additional memory flags. 
To allocate named shared memory, the pszName field is set to the name of the object. 
The OBJ_GETTABLE and OBJ_GIVEABLE memory allocation flags are not allowed for named 
shared memory. To allocate unnamed shared memory, the pszName field is set to NULL 
and at least one of the OBJ_GETTABLE or OBJ_GIVEABLE flags must be specified. There 
are some macros defined in the BSEMEMF.H header file, which is included by the 
BSEDOS.H header file: 

#define fSHARE (OBJ_GETTABLE + OBJ_GIVEABLE) 

#define fPERM (PAG_EXECUTE + PAG_READ + PAG_WRITE) 

#define fALLOCSHR (0BJ_TILE + PAG_COMMIT + fSHARE + fPERM) 

#define fGETNMSHR (fPERM) 

#define fGETSHR (fPERM) 

#define fGIVESHR (fPERM) 

After shared memory has been committed, the protection flags and commit state of 
the pages of memory can be changed with the DosSetMem API just as they were for 
nonshared memory. Shared memory can also be queried as before using the DosQuerymem 
API. If a page of shared memory has been committed, the additional flag of PAG_S HARED 
will be returned for the shared pages when DosQueryMem is used. Once a page of shared 
memory has been committed, it cannot be decommitted. 

For named shared memory, the DosGetNamedSharedMem API is used by other pro¬ 
cesses to obtain access to the memory object: 



ULONG cb 

ULONG flag 
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APIRET APIENTRY DosGetNamedSharedMem (PPVOID ppBaseAddress, 
PSZ pszSharedMemName, ULONG ulAttributeFlags) 


PPVOID ppBaseAddress 

PSZ pszSharedMemName 


ULONG ulAttributeFlags 

PAG_READ 

PAG_EXECUTE 

PAG_WRITE 


Address of pointer to 
receive memory address. 
Name of the named shared 
memory object. This name 
has the form 

\SHAREMEM\name . name 
can be any name that meets 
the criteria for a valid OS/2 
filename. 

Desired access protection 
for the shared memory: 

Read access. 

Execute access (executable 
code). 

Write access (includes read 
and execute access). 


If a named shared memory object with the specified name exists, the process is given 
access to the memory, and its address is returned in ppBaseAddress. The following ex¬ 
ample shows one process allocating 32K of named shared memory and another process 
gaining access to it. 

Process 1: 


PVOID pMem; 


if 

{ 

} 


(IDosAllocSharedMem 
fPERM ! 


(&pMern, "WSHAREMEMWOBJECTI " , 
PAG_COMMIT 1 0BJ_TILE)) 


0X8000L, 


strcpy ((PSZ)pMem, "Hello Process 2"); 


Process 2: 


PVOID pMem; 

if (!DosGetNamedSharedMem (&pMem, "WSHAREMEMWOBJECTI", fPERM)) 

{ 

strcpy ((PSZ)pMem, "Hello to you Process 1"); 

} 

For unnamed shared memory, there are two ways that memory access can be obtained 
by a second process. The first is for the second process to use the DosGetSharedMem API: 
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APIRET APIENTRY DosGetSharedMem (PVOID pBaseAddress, 
ULONG ulAttributeFlags) 


PVOID pBaseAddress 
ULONG ulAttributeFlags 


PAG_READ 

PAG_EXECUTE 

PAG_WRITE 


The base address of the 
shared memory object. 
Desired access protection 
for the shared memory: 

Read access. 

Execute access (executable 
code). 

Write access (includes 
read and execute access). 


In order for the DosGetSharedMem request to succeed, the memory object must have 
been allocated with the OBJ_GETTABLE flag, and the requested ulAttributeFlags must 
be compatible with the current protection flags for the memory object. Note that the 
address passed in pBaseAddress must be the base address of the memory object. The 
following example shows one process allocating 32K of unnamed shared memory, pass- 
ing the address to the second process, and the second process gaining access to it. 

Process 1: 


#define WM_USER_SHARED_MEM WM USER+1 


PVOID pMem; 

HWND hWndProcess2; 

if (IDosAllocSharedMem (&pMem, NULL, 0X8000L, 
fPERM ] PAG_COMMIT | OBJ_TILE | OBJ_GETTABLE ] 

OBJ_GIVEABLE)) 

{ 

strcpy ((PSZ)pMem, "Hello Process 2"); 

WinSendMsg (hWndProcess2, WM_USER_SHARED_MEM, (MPARAM)pMem, 0L); 


Process 2: 

#define WM_USER_SHARED_MEM WM_USER+1 

PVOID pMem; 

MRESULT EXPENTRY MainWndProcProc (HWND hWnd, ULONG msg, 
MPARAM mpl, MPARAM mp2) 

{ 

switch (msg) 

{ 


case WM_USER_SHARED MEM: 
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pMem = (PVOID)mpl; 
if (!DosGetSharedMem (pMem, fPERM)) 

strcpy ((PSZ)pMem, "Hello to you Process 1"); 
return (0L); 

} 

return (WinDefWindowProc (hWnd, msg, mpl, mp2)); 

} 

In this example, we used a message (WM_USER_SHARED_MEM) to pass the address of 
the memory object to Process 2. It could also have been done other ways using interprocess 
communication or through global data in a DLL using a single data segment. 

The second way for a process to gain access to unnamed shared memory is to have 
a process that currently has access to explicitly give access to another process. This is 
accomplished with the DosGiveSharedMem API: 

APIRET APIENTRY DosGiveSharedMem (PVOID pBaseAddress, 

PID idProcessID, ULONG ulAttributeFlags) 

The base address of the 
shared memory object. 
Process identifier of 
process to be given access. 
Desired access protection 
for the shared memory: 

PAG_READ Read access. 

PAG_EXECUTE Execute access (executable 

code). 

PAG_WRITE Write access (includes 

read and execute access). 

In order for the DosGiveSharedMem request to succeed, the memory object must have 
been allocated with the OBJ_GIVEABLE flag, and the requested ulAttributeFlags must 
be compatible with the current protection flags for the memory object. Note again that 
the address passed in pBaseAddress must be the base address of the memory object. The 
following example shows one process allocating 32K of unnamed shared memory, giving 
access of it to another process, and then passing the address to the second process. 

Process 1: 

#define WM_USER_SHARED_MEM WM_USER+1 

PVOID pMem; 

PID pidProcess2; 

HWND hWndProcess2; 


PVOID pBaseAddress 
PID idProcessID 
ULONG ulAttributeFlags 


if (!DosAllocSharedMem (&pMem, NULL, 0X8000L, 
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fPERM | PAG_COMMIT | 0BJ_TILE J OBJ_GETTABLE | 

OBJ_GIVEABLE)) 

{ 

strcpy ((PSZ)pMem, "Hello Process 2"); 
if (IDosGiveSharedMem (pMem, pidProcess2, fPERM)) WinSendMsg 
(hWndProcess2, WM_USER_SHARED_MEM, (MPARAM)pMem, 0L) ; 
else 

DosFreeMem (pMem); 

} 

Process 2: 

#define WM_USER_SHARED_MEM WM_USER+1 

PVOID pMem; 

MRESULT EXPENTRY MainWndProcProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

switch (msg) 

{ 

case WM_USER_SHARED_MEM: 
pMem = (PVOID)mpl; 

strcpy ((PSZ)pMem, "Hello to you Process 1"); return (0L); 

} 

return (WinDefWindowProc (hWnd, msg, mpl, mp2)); 

} 

Again, in this example, we used a message (WM_USER_$HARED_MEM) to pass the ad¬ 
dress of the memory object to Process 2. Process 2 does not have to do anything to the 
memory object in order to use it since Process 1 has already given it access. The identifier 
for Process 2 must have been passed to Process 1 by using interprocess communication 
or through global data in a DLL by using a single data segment. 

It is important to note again that each process is responsible for calling DosFreeMem 
for each shared memory object it has access to when it is done using the memory. 

We showed in an earlier section how to improve the memory allocation performance 
and reduce the amount of memory management overhead on the application by using 
suballocated memory. Suballocated memory can also be used for shared memory objects, 
but you should use the DOSSUB_SERIALIZE flag when allocating the shared memory object. 
OS/2 creates a semaphore specifically for the shared memory object and automatically 
requests access to the semaphore for all memory suballocation requests and free opera¬ 
tions. Following is an example of creating a shared memory object for use by memory 
suballocation and what is required by each process sharing this memory. 
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Process 1 allocates a 128K block of shared memory and initializes it for memory 
suballocation. 

Process 1: 

PVOID pHeap; 

if (JDosAllocSharedMem f&pHeap, NULL, 0X20000L, 

fPERM | OBJ_GETTABLE) && 

!DosSubSet (pHeap, DOSSUB_INIT | DOSSUB_SPARSE_OBJ | 

DOSSUB_SERIALIZE, 

0X20000L) 

{ 

PVOID pSubMem; 

if (IDosSubAlloc (pHeap, &pSubMem, 0X1000L,)) 

{ 

DosSubFree (pHeap, pSubMem, 0X1000L); 

} 

} 

Any processes wanting to share this memory and use the suballocation must first gain 
access to the memory and then call DosSubSet. The call to DosSubSet does not reinitialize 
the memory for suballocation but does give the process access to the semaphore created 
by OS/2 for serializing requests to the memory object. 

Process 2: 

PVOID pHeap; 

if (IDosGetSharedMem (pHeap, fPERM) && 

!DosSubSet (pHeap, DOSSUB_SPARSE_OBJ j DOSSUB_SERIALIZE)) 

{ 

PVOID pSubMem; 

if (IDosSubAlloc (pHeap, &pSubMem, 0X1000L,)) 

{ 

DosSubFree (pHeap, pSubMem, 0X1000L); 

} 

} 

When each process is finished with the shared memory object, it must first call 
DosSubllnsetMem to release its access to the semaphore that OS/2 created. It must then 
call DosFreeMem to free the shared memory for the process. 
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Process 1: 

/* Termination code for process */ 
DosSubUnsetMem (pHeap); 

DosFreeMem (pHeap); 


Process 2: 

/* Termination code for process */ 
DosSubUnsetMem (pHeap); 

DosFreeMem (pHeap); 


Converting from Unshared to Shared Memory 

There are many times when you have a memory object that is allocated as a private memory 
object, and you need to pass the information to another process or even copy it to the 
clipboard. In those circumstances, it is necessary to move the data to shared memory. 
The following function shows the steps to take a private memory object and convert it to 
a shared memory object. This process simply requires us to determine the size of the private 
memory object, allocate a shared memory object of the same size, and copy the data. The 
function ConvertToSharedMemory assumes that the committed pages of the private data 
object consist of contiguous pages starting at the base address. 

PVOID ConvertToSharedMemory (PVOID pPrivateMem, BOOL bFree) { 

/* Convert the private memory pointed to by pPrivateMem to shared 
memory. If bFree is specified, free the memory pointed 
to by pPrivateMem after creating the shared memory 
object. Return NULL if the convert fails. */ 

PVOID pSharedMem = NULL; 

ULONG ulSize; 

ULONG ulFlags; 

ulSize = OxFFFFFFFFL; 

if ( IDosQueryMem (pPrivateMem, &ulSize, &ulFlag) && 

(ulFlag & PAG_COMMIT) && 

IDosAllocSharedMem (&pSharedMem, NULL, ulSize, 

(UlFlag & fALLOC) ] fSHARE) ) 

{ 

memcpy (pSharedMem, pPrivateMem, ulSize); 
if (bFree) 

DosFreeMem (pPrivateMem); 

} 

return (pSharedMem); 

} 
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In order to successfully convert the pointer, there must be committed memory in the 
private memory object, and the shared memory object must be successfully allocated: 

if ( !DosQueryMem (pPrivateMem, &ulSize, &ulFlag) && 

(ulFlag & PAG_COMMIT) && 

!DosAllocSharedMem (&pSharedMem, NULL, ulSize, 

(ulFlag & fALLOC) | fSHARE) ) 

The flags used for the DosAllocSharedMem call are the existing flags for the private 
memory object (including the PAG_COMMIT) plus the f SHARE flags. 

The MEMMAP Application 

This sample application demonstrates most features and API calls needed to query memory 
within OS/2. 


MEMMAP’s Files 

The files necessary to build the MEMMAP application are the following: 

MEMMAP.DEF 
MEMMAP.DLG 
MEMMAP.C 
MEMMAP. H 
MEMMAP.RC 
MEMMAP.ICO 


MEMMAP.C 


/* 


MemMap Program 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#define INCL_GPI 
#define INCL_D0SERR0RS 
#include <os2.h> 
#include <stdio.h> 
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#include "memmap.h" 

#include ".. \..\common\about.h" 

/* Exported Functions */ 

MRESULT EXPENTRY MainDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Local Functions */ 

VOID CenterWindow (HWND); 

VOID MemError (PSZ); 

ULONG Parseltem (PSZ,ULONG); 

VOID QueryMemory (VOID); 

HAB hab; 

CHAR szTitle[64]; 

HWND hWndFrame; 

HWND hWndMemList; 

HWND hWndStartAddress; 

ULONG ulStartAddress = 0L; 

CHAR szStartAddress[9] = "00000000"; 

PVOID pStartAddress = (PVOID)szStartAddress; 

/* Undocumented menu message */ 

#define MM_QUERYITEMBYPOS 0x01f3 

#define MAKE_16BIT_P0INTER(p) \ 

((PVOID)MAKEULONG(LOUSHORT(p),(HIUSHORT(p) « 3) j 7)) 


int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinLoadDlg (HWND_DESKTOP, HWND_DESKTOP, 

MainDlgProc, 0, ID_APPNAME, NULL); 

WinSendMsg (hWndFrame, WM_SETICON, 

(MPARAM)WinLoadPointer (HWND_DESKTOP, 0, ID_APPNAME), NULL); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 
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WinTerminate (hab); 
return (0); 


VOID AddAboutToSystemMenu(HWND hWndFrame) 

{ 

MENUITEM mi; 

HWND hWndSysSubMenu; 

WinSendMsg (WinWindowFromID (hWndFrame, FID_SYSMENU), 
MM_QUERYITEMBYPOS, 0L, MAKE_16BIT_P0INTER(&mi)); 
hWndSysSubMenu = mi.hwndSubMenu; 
mi.iPosition = MITJEND; 
mi.atStyle = MIS_SEPARATOR; 
mi.afAttribute = 0; 
mi.id = -1; 

mi.hwndSubMenu = 0; 
mi.hltem = 0; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), NULL); 
mi.afStyle = MIS_TEXT; 
mi.id = IDM_ABOUT; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), 

"About..."); 
return; 

} 

VOID CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd,&Rectl); 

WinSetWindowPos (hWnd, HWND_TOP, (ulScrWidth-Recti.xRight)/2, 
(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_M0VE | SWP_ACTIVATE); 
return; 

} 

VOID MemError (PSZ pszMessage) 

{ 

WinMessageBox (HWND_DESKTOP, hWndFrame, pszMessage, 

"Memory Map", 0, MB_ERR0R | MB_OK); 
return; 

} 

ULONG Parseltem (PSZ szltem, ULONG CurPos) 

{ 

ULONG EndPos = CurPos + 8; 

ULONG ulMem = 0; 
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for (; CurPos < EndPos; CurPos++) 

{ 

if (szItem[CurPos] != 1 1 ) 
ulMem = ulMem*16 + 

((szItem[CurPos] <= '9') ? (szItem[CurPos] - '0') : 

(szItem[CurPos] - 'A' + 10)) 

} 

return (ulMem); 


VOID QueryMemory () 

{ 

char szText[90]; 

ULONG ulAddress, 

ulEndAddress, 
ulPage, 
ulSize, 
ulFlags; 

APIRET RetCode; 

WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP, SPTR_WAIT, FALSE)); 
WinEnableWindowllpdate (hWndMemList, FALSE); 
ulAddress = ulStartAddress; 

ulEndAddress = ulStartAddress + 0x02000000; /* 32 MB max */ 

if (ulEndAddress > 0x20000000) 
ulEndAddress = 0x20000000; 
ulPage = 0L; 

sprintf (szText, "%081x . 

ulAddress); 

WinUpper (hab, 0, 0, szText); 
while (ulAddress < ulEndAddress) 

{ 

ulSize = 0XFFFFFFFF; 

if (! (RetCode = DosQueryMem ((PVOID)ulAddress, SculSize^ 
&ulFlags))) 

{ 

if (ulFlags == PAG_FREE) 
ulSize = 0x1000; 
else 

ulSize = (ulSize + 0xFFF) & 0xFFFFF000; 
if (ulFlags & PAG_BASE) 
szText[42] = 1 * 1 ; 

while (ulSize && (ulAddress < 0x20000000)) 

{ 

if (UlFlags & PAG_COMMIT) 
szText[10 + ulPage*2] = 'C 1 ; 
else if (!(ulFlags & PAG_FREE)) 
szText[10 + ulPage*2] = 'A'; 
ulAddress += 0x1000; 
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ulSize -= 0x1000; 

ulPage++; 

if (ulPage == 16) 


{ 

if (ulFlags & PAG_SHARED) 


sprintf 

(&szText[43], "%s”, 

"Shared ") 

else if (ulFlags & PAG_FREE) 


sprintf 

(&szText[43], "%s“, 

"Free ") 

else 



sprintf 

(&szText[43], "%s“, 

"Private") 


if (WinlnsertLboxItem ( 

WinWindowFromID (hWndFrame, IDLJVIEMLIST), 
LIT_END, szText) < 0) 

break; 
ulPage = 0; 
sprintf (szText, 

"%081x . 

ulAddress); 

WinUpper (hab, 0, 0, szText); 

} 

} 

} 

else if (RetCode == ERROR_INVALID_ADDRESS) 

{ 

ulAddress += 0x10000; 

sprintf (&szText[43], "%s", "Invalid"); 

WinlnsertLboxItem (WinWindowFromID (hWndFrame, IDL_MEMLIST), 
LIT_END, szText); 
sprintf (szText, 

"%081x . 

ulAddress); 

WinUpper (hab, 0, 0, szText); 

} 

else 

sprintf (szText, "Error querying memory address %081x", 
ulAddress); 

MemError (szText); 
break; 

} 

} 

WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP,SPTR_ARROW,FALSE)); 
WinEnableWindowUpdate (hWndMemList, TRUE); 

} 


MRESULT EXPENTRY MainDlgProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 
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{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_INITDLG: 

CenterWindow (hWnd); 

/* Add the About menu item to the system menu */ 
AddAboutToSystemMenu (hWnd); 

hWndMemList = WinWindowFromID (hWnd, IDL_MEMLIST); 

hWndStartAddress = WinWindowFromID (hWnd, IDB_STARTADDRESS); 

WinSendMsg (hWndStartAddress, SPBM_SETTEXTLIMIT, 

(MPARAM)8, (MPARAM)0); 

WinSendMsg (hWndStartAddress, SPBM_SETARRAY, 
(MPARAM)&pStartAddress, (MPARAM)1L); 

WinSendMsg (hWndStartAddress, SPBM_SETCURRENTVALUE, 

(MPARAM)0L, (MPARAM)0L); 

WinSetFocus (HWND_DESKTOP, hWndStartAddress); 

WinPostMsg (hWnd, WM_COMMAND, (MPARAM)IDB REFRESH, 0L)• 
break; 

case WM_C0NTR0L: 
switch (LOUSHORT(mpl)) 

{ 

case IDL_MEMLIST: 

if (HIUSHORT(mpl) == LN_SELECT) 

{ 

WinQueryLboxItemText (hWndMemList, 

WinQueryLboxSelectedItem((HWND)mp 2 ), 
szStartAddress,9); 

ulStartAddress = Parseltem (szStartAddress, 0); 
WinSendMsg (hWndStartAddress, SPBM_SETARRAY, 

(MPARAM)&pStartAddress, (MPARAM)1L); 

break; 

case IDB_STARTADDRESS: 

if (HIUSHORT(mpl) == SPBNJJPARROW) 

ulStartAddress = (ulStartAddress + 0x10000) & 0x1FFFFFFF 
else if (HIUSHORT(mpl) == SPBN_DOWNARROW) 

ulStartAddress = (ulStartAddress - 0x10000) & 0x1FFFFFFF 
sprintf (szStartAddress,"%081x",ulStartAddress); 
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WinUpper (hab, 0, 0, szStartAddress); 

WinSendMsg (hWndStartAddress, SPBM_SETARRAY, 

(MPARAM)&pStartAdd re s s, (MPARAM)1L); 
break; 

} 

break; 

case WM_COMMAND: 
case WM_SYSCOMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDB_REFRESH: 

WinSendDlgltemMsg (hWndFrame, IDL_MEMLIST, LM_DELETEALL, 
0L, 0L); 

QueryMemory (); 

WinSendMsg (hWndMemList, LM_SELECTITEM, 

(MPARAM)0, (MPARAM)TRUE); 
break; 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

case SC_CLOSE. 

WinPostMsg (hWnd, WM_QUIT, 0L, 0L); 
break; 

default: 

bHandled = (msg == WM_COMMAND); 

} 

break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 


return (mReturn); 



Chapter^ Memory Management 


MEMMAP.H 


/* 


MemMap Header File 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define ID_APPNAME 1 

#define IDL_MEMLIST 10 

#define IDB_REFRESH 11 

#define IDT__PAGES 12 

#define IDB_STARTADDRESS 13 

#define IDM ABOUT 100 


MEMMAP.RC 


/* 


MemMap Resource File 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "memmap.h" 

ICON ID_APPNAME MEMMAP.ICO 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Memory Map Application" 

END 

rcinclude memmap.dlg 
rcinclude ..\.\common\about.dig 
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MEMMAP.DLG 


/* 


MemMap Dialog 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE ID_APPNAME LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Memory Map", ID_APPNAME, 36, 17, 302, 165, 

WS_VISIBLE | FS_DLGBORDER, 

FCF_SYSMENU 1 FCF_TITLEBAR | FCF_DLGBORDER | 

FCF_TASKLIST | FCF_ICON; 

BEGIN 

LTEXT "Address", -1, 15, 145, 37, 8 

LTEXT "Page", -1, 139, 154, 24, 8 

LTEXT "01 23456789ABCDEF", IDT_PAGES, 

64, 145, 174, 8 

PRESPARAMS PP_FONTNAMESIZE, "10.System Monospaced" 
LTEXT "Type", -1, 248, 145, 22, 8 

LTEXT ". = Free A = Allocated C = Committed * = Base", 

-1, 77, 6, 207, 8 

LISTBOX IDL_MEMLIST, 10, 36, 282, 107 

PRESPARAMS PP_FONTNAMESIZE, "10.System Monospaced" 
PUSHBUTTON "Refresh", 11, 8, 4, 45, 14 
LTEXT "Start Address", DID_CANCEL, 9, 23, 60, 8 

CONTROL "", IDB_STARTADDRESS, 73, 20, 64, 12, WC_SPINBUTTON, 
SPBS_ALLCHARACTERS | SPBS_READONLY | 

SPBSJVIASTER | SPBS_JUSTRIGHT | 

SPBS_FASTSPIN | WS_GR0UP | WS_TABSTOP | WS_VISIBLE 
PRESPARAMS PP_FONTNAMESIZE, "10.System Monospaced" 

END 

END 


Using MEMMAP 

Add the MEMMAP application icon to a window and open the program. You should 
see a display similar to Figure 9.5. 

The MEMMAP application merely displays a map of the memory available to the 
MEMMAP process. The memory will be marked Free, Allocated, Committed, or Base. 
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\{;4 Memory fvto 


Start Address '|”00000000^ 

f —..—- . • „ 

j Afresh | . = Free A = Allocated C = Committed * = Ba 


Remember base memory is the starting address of a block of memory. If a process 
allocated two pages of memory, the first page will be marked as base, the second will not. 
Take a look at the memory map that MEMMAP displays. Each asterisk signals the 
beginning of a new allocated block. Gaps indicate large blocks of memory. 

Because the only memory available to the MEMMAP application is that which has 
been allocated for its own process, the map will not change much between differing 
instances of the application. 

Understanding MEMMAP’s Code 

The code for MEMMAP is similar to that of the MEMORY sample application, which 
is detailed following the MEMMAP application. The major difference lies in the 
QueryMemory function, which is detailed in following text. Work through understand¬ 
ing this smaller portion of both applications before going on to tackle the MEMORY 
application. 

The QueryMemory function will query 32M of memory starting at ulStartAddress. 
We stop at 32M because our list box can only hold so many entries. This function will 
check for all the features of paged memory allocation, as well as correct for a couple of 
OS/2 quirks. 

We begin by calculating our ending address and ensuring it is less than our 512M 
limit. We now loop until we have reached the end of our range. The call to DosQueryMem 
queries the maximum memory size starting at our current address. Remember that if the 
address queried is the first page of a memory object, the PAG_BASE flag is set. If the page 
is not currently allocated, the PAG_FREE flag is set. Also, the DosQueryMem call will query 
pages until it finds a page with a memory flag different from the first page queried or 
until it finds the first page of the next allocated memory object. 
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Figure 9.5. 

MEMMAP application. 
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Each call to DosQueryMem will start at the address in ulAddress and return the size 
of the memory pages that have the same flags as the first page at ulAddress. The ul Flags 
variable will contain those flags. Here, we discover a quirk in the DosQueryMem function. 
If the first page queried is free memory (PAG_FREE), the size of the memory object re¬ 
turned is not a believable value. In other words, we can be sure that only one page is marked 
as PAG_FREE. Do not use the size returned in ulSize as the size of contiguous PAG_FREE 
pages. For this reason, if the PAG_FREE bit is set, we reset ulSize to one 4K page; other¬ 
wise, we round the size to a 4K page boundary. At this point, we loop through the memory 
size returned, setting the appropriate page flags for allocated and committed pages. 

We also output the type of memory object each 64K block of memory represents 
(Shared, Free, or Private). At this point ulAddress contains the address of the first page 
past the memory object just processed. If the return code from DosQueryMem is 
ERROR_INVALID_ADDRESS, we are unable to query that address, so we skip that memory 
object and go to the next 64K block. 

Remember that a program can query memory only for the current process. It does 
not have access to another process’s address space. This function, thus, only queries the 
memory allocated for the MemMap program. You, however, can use this function and 
add it to any program to query its allocated and committed memory. 

The MEMORY Application 

This sample application demonstrates allocating, committing, freeing, and changing the 
access rights to blocks of memory. It also utilizes the techniques from the MEMMAP 
program to display the status of each page of an allocated memory object. 

MEMORY’S Files 

The files necessary to build the MEMORY application are the following: 

MEMORY.C 

MEMORY.H 

MEMORY.DEF 

MEMORY.RC 

ALLOCATE.DLG 

MEMORY.DLG 

MEMORY.ICO 
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MEMORY. C 


/* 


Memory Program 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#include <os2.h> 

#include <stdio.h> 

#include "memory.h" 

#include "..\.\common\about.h" 

#define WAIT_POINTER WinSetPointer (HWND_DESKTOP, \ 

WinQuerySysPointer (HWND_DESKTOP,SPTR_WAIT,FALSE)); 
#define ARROW_POINTER WinSetPointer (HWND_DESKTOP, \ 

WinQuerySysPointer (HWND_DESKTOP,SPTR_ARROW,FALSE)); 

/* Exported Functions */ 

MRESULT EXPENTRY AllocateDlgProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY MainDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Local Functions */ 

VOID CenterWindow (HWND); 

VOID ChangeAccessRights (USHORT); 

VOID ChangeCommitState (BOOL); 

PSZ FormatMemListltem (PVOID,LONG,ULONG,ULONG); 

PSZ FormatPageListltem (PVOID,ULONG); 

VOID MemError (PSZ); 

ULONG Parseltem (PSZ,ULONG); 

VOID QueryMemory (SHORT); 

HAB hab; 

CHAR szTitle[64]; 
char szListItem[40]; 
char szPageItem[20]; 

HWND hWndFrame; 

HWND hWndMemList; 

HWND hWndPageList; 

BOOL bCommitted = FALSE; 

BOOL bShared = FALSE; 

BOOL bRead = TRUE; 


/* Application Frame window handle */ 
/* Memory List box window handle */ 
/* Page List box window handle */ 

/* Current settings in list box */ 
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BOOL bWrite = TRUE; 

BOOL bExecute = TRUE; 

BOOL bTiled = FALSE; 

#define FONTNAMELEN 21 /* length + 1 */ 

CHAR szListboxFont[] = "10.System Monospaced"; 

/* Undocumented menu message */ 

#define MM_QUERYITEMBYPOS 0x01f3 

#define MAKE_16BIT_P0INTER(p) \ 

((PVOID)MAKEULONG(LOUSHORT(p),(HIUSHORT(p) « 3) | 7)) 


int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinLoadDlg (HWND_DESKTOP, HWND_DESKTOP, 

MainDlgProc, 0, ID_APPNAME, NULL); 

WinSendMsg (hWndFrame, WM_SETICON, 

(MPARAM)WinLoadPointer (HWND_DESKTOP, 0, ID_APPNAME), NULL); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 

} 

VOID AddAboutToSystemMenu(HWND hWndFrame) 

{ 

MENUITEM mi; 

HWND hWndSysSubMenu; 

WinSendMsg (WinWindowFromID (hWndFrame, FID_SYSMENU), 
MM_QUERYITEMBYPOS, 0L, MAKE_16BIT_P0INTER(&mi)); 
hWndSysSubMenu = mi.hwndSubMenu; 
mi.iPosition = MIT_END; 

mi.atStyle = MIS_SEPARATOR; 

mi.afAttribute = 0; 

mi.id = -1; 
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mi.hwndSubMenu = 0; 

mi.hltem = 0; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), NULL); 
mi.afStyle = MIS_TEXT; 

mi.id = IDM_ABOUT; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), 

"About...; 
return; 


VOID CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd,&Rectl); 

WinSetWindowPos (hWnd, HWND_TOP, (ulScrWidth-Recti.xRight) 12, 
(ulScrHeight-Rectl.yTop)/2, 0, 0, SWP_MOVE | SWP_ACTIVATE); 
return; 

} 


PSZ FormatMemListltem (PVOID pMem, LONG lAllocRequest, 

ULONG ulAllocated, ULONG ulCommitted) 

sprintf (szListltem,"%081x %81x %81x %81x", 

(ULONG)pMem, (ULONG)lAllocRequest, ulAllocated, ulCommitted); 
WinUpper (hab, 0, 0, szListltem); 
return (szListltem); 


PSZ FormatPageListltem (PVOID pMem, 

{ 

sprintf (szPageltem, "%081x 
szPageItem[9] = (CHAR)(ulFlags & 

szPageItem[10] = (CHAR)(ulFlags & 

szPageItem[11] = (CHAR)(ulFlags & 

szPageltem]12] = (CHAR)(ulFlags & 

szPageltem]13] = (CHAR)(ulFlags & 

WinUpper (hab, 0, 0, szPageltem); 
return (szPageltem); 

} 


ULONG ulFlags) 


", pMem); 

PAG_READ ? 1 R 1 
PAG_WRITE ? 'W 1 
PAG_EXECUTE ? * E' 
PAG_COMMIT ? 'C' 
PAG_SHARED ? 'S' 


VOID MemError (PSZ pszMessage) 

{ 

WinMessageBox (HWNDJDESKTOP, hWndFrame, pszMessage, 
"Memory Allocation", 0, MB_ERR0R ] MB_OK); 


) 

) 

) 

) 

) 
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return; 

} 

ULONG Parseltem (PSZ szltem, ULONG CurPos) 

{ 

ULONG EndPos = CurPos + 8; 

ULONG ulMem = 0; 

for (; CurPos < EndPos; CurPos++) 

{ 

if (szItem[CurPos] != 1 ') 
ulMem = ulMem*16 + 

((szItem[CurPos] <= '9') ? (szItem[CurPos] - '0') : 

(szItem[CurPos] - 'A' + 10)); 

} 

return (ulMem); 


VOID ChangeAccessRights (USHORT usRights) 

{ 

ULONG ulAddress; 

SHORT sSel = -1; 

ULONG ulFlags = 0L; 

BOOL bError = FALSE; 

WAIT_POINTER 

ulFlags = (ULONG)(usRights & 0x0007); 

while ((sSel = (SHORT)WinSendMsg (hWndPageList, 

LM_QUERYSELECTION, MPFROMSHORT(sSel),(MPARAM)NULL)) != LIT_NONE) 

{ 

WinQueryLboxItemText (hWndPageList, sSel, szPageltem, 20); 

ulAddress = ParseltemfszPageltem, 0); 

if (!DosSetMem ((PVOID)ulAddress, 0x1000, ulFlags)) 

{ 

ULONG ulNewFlags; 

ULONG ulSize = 0x1000; 

DosQueryMem ((PVOID)ulAddress, &ulSize, &ulNewFlags); 
WinSetLboxItemText (hWndPageList, sSel, 

FormatPageListltem ((PVOID)ulAddress, ulNewFlags)); 

} 

else 

{ 

char szError[40]; 
if (szPageItem[12] != 'C 1 ) 

{ 

if (IbError) 

MemError ( 

"Cannot change access rights of decommitted pages"); 
bError = TRUE; 

} 

else 
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{ 

sprintf (szError, "Unable to change rights for page %081x", 
ulAddress); 

MemError (szError); 
break; 

} 

} 

} 

ARROW_POINTER 
return; 

} 

VOID ChangeCommitState (BOOL bCommit) 

{ 

ULONG ulAddress; 

ULONG ulFlags; 

ULONG ulCommitted; 

SHORT sSel = -1; 

WAIT^POINTER 

ulCommitted = ParseItem(szListItem, 27); 
while ((sSel = (SHORT)WinSendMsg (hWndPageList, 

LM_QUERYSELECTION, MPFROMLONG(sSel),(MPARAM)NULL)) != LITJMONE) 

{ 

WinQueryLboxItemText (hWndPageList, sSel, szPageltem, 20); 
ulAddress = ParseItem(szPageItem,0); 
if (bCommit) 

{ 

/* If already committed nothing to do */ 
if (szPageItem[12] == 1 C') 
continue; 

ulFlags = PAG_COMMIT; 
if (szPageItem[9] == 'R') 
ulFlags |= PAG__READ; 
if (szPageItem[10] == 1 W 1 ) 
ulFlags J= PAG_WRITE; 
if (szPageltemf11] == ‘E') 

UlFlags |= PAG_EXECUTE; 

} 

else 

{ 

/* If already decommitted nothing to do */ 
if (szPageItem[12] == 1 ') 
continue; 

ulFlags = PAG_DECOMMIT; 

} 

if (!DosSetMem ((PVOID)ulAddress, 0x1000, ulFlags)) 

{ 

/* Requery the item. Decommitting causes flags to be reset 
to default (flags defined when memory was allocated) */ 

ULONG ulSize = 0x1000; 
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DosQueryMem ((PVOID)ulAddress, &ulSize, &ulFlags); 
WinSetLboxItemText (hWndPageList, sSel, 

FormatPageListltem ((PVOID)ulAddress, ulFlags)); 
if (bCommit) 

ulCommitted += 0x1000; 
else 

ulCommitted -= 0x1000; 

} 

else 

{ 

char szError[40]; 

sprintf (szError, "Unable to %s page %081x", 

bCommit ? "commit" : "decommit", ulAddress); 

MemError (szError); 
break; 

} 

} 

sprintf (&szListItem[27], "%81x", ulCommitted); 

WinUpper (hab, 0, 0, szListltem); 

WinSetLboxItemText (hWndMemList, 

WinQueryLboxSelectedltem(hWndMemList), szListltem); 
ARROW_POINTER 
return; 

} 

VOID QueryMemory (SHORT sSel) 

{ 

ULONG ulAddress, 

ulAllocated, 

ulCommitted, 

ulSize, 

ulFlags; 

BOOL bError = FALSE; 

BOOL bFirst = TRUE; 

WAIT_POINTER 

WinQueryLboxItemText (hWndMemList, sSel, szListltem, 40); 
WinEnableWindowUpdate (hWndPageList, FALSE); 

WinSendMsg (hWndPageList, LM_DELETEALL, 0L, 0L); 

ulAddress = Parseltem (szListltem, 0); 

ulCommitted = 0L; 

ulAllocated = 0L; 

ulSize = 0XFFFFFFFF; 

while (!DosQueryMem ((PVOID)ulAddress, &ulSize, &ulFlags) && 
(bFirst i! !(UlFlags & (PAG_BASE | PAG_FREE)))) 

{ 

bFirst = FALSE; 

ulAllocated += ulSize; 
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if (ulFlags & PAG_COMMIT) 
ulCommitted += ulSize; 
while (ulSize) 

{ 

if (WinlnsertLboxItem (hWndPageList, LIT_END, 

FormatPageListltem ((PVOID)ulAddress, ulFlags)) < 0) 

{ 

if (!bError) 

MemError ("Unable to add any more list items"); 
bError = TRUE; 

} 

ulAddress += 0x1000; 
ulSize -= 0x1000; 

} 

ulSize = 0XFFFFFFFF; 

} 

WinEnableWindowUpdate (hWndPageList, TRUE); 

WinSendMsg (hWndPageList, LM_SELECTITEM, (MPARAM)0L, (MPARAM)TRUE) 
sprintf (&szListItem[18], "%81x%81x", ulAllocated, ulCommitted); 
WinUpper (hab, 0, 0, szListltem); 

WinSetLboxItemText (hWndMemList, sSel, szListltem); 

ARROW POINTER 


return; 

} 


MRESULT EXPENTRY AllocateDlgProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 


{ 


LONG IMemAlloc; 


switch (msg) 

{ 


case WM INITDLG: 


CenterWindow (hWnd); 

WinCheckButton (hWnd, 

(bCommitted ? IDB_COMMITTED : IDB_UNCOMMITTED), TRUE); 
WinCheckButton (hWnd, 


(bShared ? IDB_SHARED 


IDB_NONSHARED), TRUE); 


WinCheckButton (hWnd, IDB_READ, bRead); 

WinCheckButton (hWnd, IDB_WRITE, bWrite); 

WinCheckButton (hWnd, IDB_EXECUTE, bExecute); 

WinCheckButton (hWnd, IDB_TILED, bTiled); 

WinSendDlgltemMsg (hWnd, IDB_NUMBYTES, SPBM_SETTEXTLIMIT, 
(MPARAM)7, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDB_NUMBYTES, SPBM_SETLIMITS, 
(MPARAM) 0X00100000, (MPARAM)1L); 

WinSendDlgltemMsg (hWnd, IDB_NUMBYTES, SPBM_SETCURRENTVALUE, 
(MPARAM)1,(MPARAM)0L); 
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WinSendDlgltemMsg (hWnd, IDB_REPEAT, SPBM_SETTEXTLIMIT, 
(MPARAM)4, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDB_REPEAT, SPBM_SETLIMITS, 
(MPARAM)9999L,(MPARAM)1L); 

WinSendDlgltemMsg (hWnd, IDB_REPEAT, SPBM_SETCURRENTVALUE, 
(MPARAM)1,(MPARAM)0L); 

WinSetFocus (HWND_DESKTOP, 

WinWindowFromID (hWnd, IDB_NUMBYTES)); 
return ((MRESULT)TRUE); 


case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case DID_0K: 

WinSendDlgltemMsg (hWnd, IDB_NUMBYTES, SPBM_QUERYVALUE, 
(MPARAM)&lMemAlloc, (MPARAM)0L); 
if (IMemAlloc) 

{ 

ULONG flags = 0L; 

BOOL bOkay; 

PVOID pMem; 

ULONG ulRepeat; 


if (IMemAlloc < 0) 

IMemAlloc = -IMemAlloc; 
bCommitted = WinQueryButtonCheckstate (hWnd, 
IDB_COMMITTED); 

bShared = WinQueryButtonCheckstate (hWnd, 

bRead = WinQueryButtonCheckstate (hWnd, 

bWrite = WinQueryButtonCheckstate (hWnd, 

bExecute = WinQueryButtonCheckstate (hWnd, 

bTiled = WinQueryButtonCheckstate (hWnd, 

if (bCommitted) 

flags |= PAG_COMMIT; 
if (bShared) 

flags j= OBJ_GETTABLE j OBJ_GIVEABLE; 
if (bRead) 

flags |= PAG_READ; 
if (bWrite) 

flags |= PAG_WRITE; 
if (bExecute) 

flags |= PAG_EXECUTE; 
if (bTiled) 

flags |= 0BJ_TILE; 


IDB_SHARED); 
IDB_READ); 
IDB_WRITE); 
IDB_EXECUTE); 
IDB_TILED); 


WinSendDlgltemMsg (hWnd, IDB_REPEAT, SPBM_QUERYVALUE, 
(MPARAM)&ulRepeat, (MPARAM)0L); 


while (ulRepeat--) 

{ 
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if (IbShared) 

bOkay = IDosAllocMem ((PPVOID)&pMem, IMemAlloc, 
flags); 

else 

bOkay = !DosAllocSharedMem ((PPVOID)&pMem, NULL, 
IMemAlloc, flags); 

if (bOkay) 

{ 

SHORT sSel; 

sSel = (SHORT)WinlnsertLboxItem (hWndMemList, 
LIT_SORTASCENDING, 

FormatMemListltem (pMem, IMemAlloc, 0L, 0L)); 
QueryMemory (sSel); 

WinSendMsg (hWndMemList, LM_SELECTITEM, 

(MPARAM)sSel, (MPARAM)TRUE); 

} 

else 

{ 

MemError ("Unable to allocate memory"); 
break; 

} 

} 

} 

/* FALL THROUGH */ 

case DID_CANCEL: 

WinDismissDlg (hWnd, TRUE); 
return (0); 

} 

break; 

} 

return (WinDefDlgProc (hWnd, msg, mpl, mp2)); 


MRESULT EXPENTRY MainDlgProc (HWND hWnd, ULONG msg, 

MPARAM mpl, MPARAM mp2) 

{ 

SHORT sSel; 

RECTL Recti; 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

static HWND hMenus[4] = { 0, 0, 0, 0 }; 

switch (msg) 

{ 

case WM_INITDLG: 

CenterWindow (hWnd); 
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hWndMemList = WinWindowFromID (hWnd, IDL_MEMLIST); 
hWndPageList = WinWindowFromID (hWnd, IDL_PAGELIST); 

/* Set the system monospaced font for the listboxes */ 
WinSetPresParam (hWndMemList, 

PP_FONTNAMESIZE, FONTNAMELEN, szListbOxFont); 
WinSetPresParam (hWndPageList, 

PP_FONTNAMESIZE, FONTNAMELEN, szListboxFont); 

/* Load the popup menus */ 

hMenus[0] = WinLoadMenu (HWND_OBJECT, 0, FREE_MENU); 
hMenus[1] = WinLoadMenu (HWND_OBJECT, 0, SELECT_MENU); 
hMenus[2] = WinLoadMenu (HWND_OBJECT, 0, STATE_MENU); 
hMenus[3] = WinLoadMenu (HWND_OBJECT, 0, RIGHTS_MENU); 

/* Add the About menu item to the system menu */ 

AddAboutToSystemMenu (hWnd); 

break; 

case WM_CONTROL: 

switch (LOUSHORT(mp1)) 

{ 

case IDL_MEMLIST: 

if (HIUSHORT(mpl) == LN_SELECT) 

QueryMemory ((SHORT)WinQueryLboxSelectedltem((HWND)mp2)); 
break; 

} 

break; 

case WM_COMMAND: 
case WM_SYSCOMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDB_ALLOCATE: 

WinDlgBox (HWND_DESKTOP, hWnd, AllocateDlgProc, 

0, IDD_ALLOCATE, NULL); 
break; 

case IDB_SELECT: 
case IDB_FREE: 
case IDB_STATE: 
case IDB_RIGHTS: 

WinQueryWindowRect (WinWindowFromID(hWnd, L0USH0RT(mp1)), 
&Rectl); 

WinMapWindowPoints (WinWindowFromID(hWnd, L0USH0RT(mp1)), 
hWnd, (PPOINTL)&Rectl, 2); 

WinPopupMenu (hWnd, hWnd, 

hMenus[LOUSHORT(mpl) / 100 - 1], 

Recti.xLeft, Recti.yTop, 
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LOUSHORT(mp1) + 1, 

PU_HCONSTRAIN j PU_VCONSTRAIN | PU_KEYBOARD | 
PU_M0USEBUTT0N1 | PU_SELECTITEM); 
break; 

case IDM_SELECT_NONE: 

WinSendMsg (hWndPageList, LM_SELECTITEM, (MPARAM)LIT_NONE, 
0L); 
break; 

case IDM_SELECT_ALL: 

{ 

SHORT sCount; 

sCount = (SHORT)WinQueryLboxCount (hWndPageList); 
while (sCount--) 

WinSendMsg (hWndPageList, LM_SELECTITEM, (MPARAM)sCount, 
(MPARAM)TRUE); 

} 

break; 

case IDM_COMMIT_SELECTED: 
case IDM_DECOMMIT_SELECTED: 

ChangeCommitState (LOUSHORT(mp1) == IDM_COMMIT_SELECTED); 
break; 

case IDM_READ: 
case IDM_WRITE: 
case IDM_EXECUTE: 
case IDM_READWRITE: 
case IDM_READEXECUTE: 
case IDM_WRITEEXECUTE: 
case IDM_READWRITEEXECUTE: 

ChangeAccessRights (LOUSHORT(mp1)); 
break; 

case IDM_FREE_SELECTED: 

if ( (sSel=(SHORT)WinQueryLboxSelectedItem (hWndMemList)) != 
LIT_NONE) 

{ 

char szMem[9]; 

ULONG ulMem; 

WinQueryLboxItemText (hWndMemList, sSel, szMem, 9); 
ulMem = Parseltem (szMem,0); 
if (IDosFreeMem ((PVOID)ulMem)) 

{ 

WinDeleteLboxItem (hWndMemList, sSel); 

WinSendMsg (hWndPageList, LM_DELETEALL, 0L, 0L); 
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if (sSel >= (SHORT)WinQueryLboxCount(hWndMemList)) 
sSel--; 

WinSendMsg (hWndMemList, LM_SELECTITEM, (MPARAM)sSel, 
(MPARAM)TRUE); 

} 

else 

MemError ("Error freeing memory"); 

} 

break; 

case IDM_FREE_ALL: 

{ 

char szMem[9]; 

ULONG ulMem; 

while (WinQueryLboxItemText (hWndMemList, 0, szMem, 9) > 0) 

{ 

ulMem = Parseltem (szMem,0); 
if (IDosFreeMem ((PVOID)ulMem)) 

WinDeleteLboxItem (hWndMemList, 0); 
else 
{ 

MemError ("Error freeing memory"); 
break; 

} 

} 

WinSendMsg (hWndPageList, LM_DELETEALL, 0L, 0L); 
break; 

} 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

case SC_CLOSE: 

WinDestroyWindow (hMenus[0]); 

WinDestroyWindow (hMenus[1j); 

WinDestroyWindow (hMenus[2]); 

WinDestroyWindow (hMenus[3]); 

WinPostMsg (hWnd, WM_COMMAND, (MPARAM)IDM_FREE_ALL, 0L); 

WinPostMsg (hWnd, WM_QUIT, 0L, 0L); 

break; 

default: 

bHandled = (msg == WM_COMMAND); 

} 

break; 
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default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefDlgProc (hWnd 3 msg, mpl, mp2); 
return (mReturn); 


MEMORY.H 


/* 


Memory Header File 
Chapter 9 

Real World Programming for OS/2 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define 

ID_APPNAME 

1 

#define 

IDD_ALLOCATE 

2 

#define 

IDLJ/IEMLIST 

10 

#define 

IDL PAGELIST 

11 

#define 

IDB_ALLOCATE 

12 

#define 

IDB_FREE 

100 

#define 

IDB_SELECT 

200 

#define 

IDB_STATE 

300 

#define 

IDB_RIGHTS 

400 

#define 

IDB_NUMBYTES 

20 

#define 

IDB_COMMITTED 

21 

#define 

IDB_UNCOMMITTED 

22 

#define 

IDB_SHARED 

23 

#define 

IDB_NONSHARED 

24 

#define 

IDB_READ 

25 

#define 

IDB WRITE 

26 

#define 

IDB_EXECUTE 

27 

#define 

IDB_TILED 

28 

#define 

IDB_REPEAT 

29 

#define 

FREE_MENU 

100 

#define 

SELECT_MENU 

200 

#define 

STATE_MENU 

300 

#define 

RIGHTS_MENU 

400 

#define 

IDM_FREE_SELECTED 

101 

#define 

IDM_FREE_ALL 

102 

#define 

IDM SELECT ALL 

201 
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#define IDM_SELECT_NONE 202 
#define IDM_C0MMIT_SELECTED 301 
#define IDM_DECOMMIT_SELECTED 302 
#define IDM_READ 401 
#define IDM_WRITE 402 
#define IDM_READWRITE 403 
#define IDM EXECUTE 404 


MEMORY.RC 


/* 


Memory Resource File 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "memory.h" 

ICON ID_APPNAME MEMORY.ICO 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Memory Allocation Program" 

END 

rcinclude memory.dig 
rcinclude allocate.dig 
rcinclude ..\.\common\about.dig 


ALLOCATE.DLG 


/* 


Memory Allocation Dialog 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_ALLOCATE LOADONCALL MOVEABLE DISCARDABLE 
BEGUN 

DIALOG "Allocate Memory", IDD_ALLOCATE, -5, 53, 264, 72, WS_VISIBLE, 
FCF_SYSMENU j 

FCF_TITLEBAR 

BEGIN 

LTEXT "Number of bytes", -1, 3, 58, 72, 8 

CONTROL "", IDB_NUMBYTES, 76, 56, 64, 12, WC_SPINBUTTON, 

SPBS_NUMERICONLY J SPBS_MASTER | 

SPBS_JUSTRIGHT | SPBS_FASTSPIN j WS_TABSTOP 
j WS_VISIBLE 
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LTEXT "Repeat", -1, 144, 58, 36, 8 

CONTROL IDB_REPEAT, 181, 56, 30, 12, WC_SPINBUTTON, 

SPBS_NUMERICONLY j SPBS_MASTER j 


SPBS_JUSTRIGHT 
| WS_VISIBLE 


GROUPBOX 

"Type", 

AUTORADIOBUTTON 

"Committed", 


WS_TABSTOP 

AUTORADIOBUTTON 

"Uncommitted", 


WS_TABSTOP | 

GROUPBOX 

"Shareability" 

AUTORADIOBUTTON 

"Shared", 


WS_TABSTOP 

AUTORADIOBUTTON 

"NonShared", 


WS_TABSTOP 

GROUPBOX 

"Access Rights 

AUTOCHECKBOX 

"Read", 

AUTOCHECKBOX 

"Write", 

AUTOCHECKBOX 

"Execute", 

AUTOCHECKBOX 

"Tiled", 

DEFPUSHBUTTON 

"OK", 

PUSHBUTTON 

"Cancel", 


END 

END 


! SPBS_FASTSPIN | WS_TABSTOP 

-1, 3, 24, 87, 31 
IDB_COMMITTED, 9, 37, 58, 10, 

IDB_UNCOMMITTED, 9, 27, 68, 10, 

-1, 97, 24, 77, 31 
IDB_SHARED, 101, 37, 44, 10, 

IDB_NONSHARED, 101, 27, 61, 10, 

, -1, 181, 15, 77, 40 
IDB_READ, 186, 37, 40, 10 
IDB_WRITE, 186, 27, 40, 10 
IDB_EXECUTE, 186, 17, 46, 10 
IDB_TILED, 102, 7, 34, 10, WS_GR0UP 
DID_0K, 4, 4, 40, 14, WS_GR0UP 
DID_CANCEL, 47, 4, 40, 14 


MEMORY.DLG 


/* 


Memory Dialog 
Chapter 9 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


MENU FREEJ/IENU PRELOAD 
BEGIN 

MENUITEM "Free Selected Item", IDM_FREE_SELECTED 
MENUITEM "Free All Items", IDM_FREE_ALL 
END 

MENU SELECT_MENU PRELOAD 
BEGIN 

MENUITEM "Select All", IDM_SELECT_ALL 
MENUITEM "Select None", IDM_SELECT_NONE 
END 

MENU STATE_MENU PRELOAD 
BEGIN 

MENUITEM "Commit Selected Pages", IDM_COMMIT_SELECTED 
MENUITEM "Decommit Selected Pages", IDM_DECOMMIT_SELECTED 
END 





Real-World Froqrammlng for U3/ JL 2.1 


MENU RIGHTS_MENU PRELOAD 
BEGIN 

MENUITEM "Read", 

MENUITEM "Write", 

MENUITEM "Execute", 

MENUITEM "Read/Write", 

MENUITEM "Read/Execute", 
MENUITEM "Write/Execute", 
MENUITEM "Read/Write/Execute", 
END 


IDM_READ 

IDM_WRITE 

IDM_EXECUTE 

IDM_READWRITE 

IDM_READEXECUTE 

IDM_WRITEEXECUTE 

IDM READWRITEEXECUTE 


DLGTEMPLATE ID_APPNAME LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 


DIALOG "Memory Allocation", 

ID_APPNAME, 

5, 11, 330, 

, 153, 

WS VISIBLE 

: ! FS DLGBORDER, 




FCF_SYSMENU | FCF_TITLEBAR ] FCF_ 

DLGBORDER | 


FCF TASKLIST | FCF_ICON; 




BEGIN 






LTEXT 

"Address", 

-1, 9, 

137, 37, 

8 


LTEXT 

"Requested" 

, -1. 55, 

137, 49, 

8 


LTEXT 

"Allocated" 

, -1, 109, 

137, 41, 

8 


LTEXT 

"Committed" 

, -1, 156, 

137, 48 

8 


LTEXT 

"Address", 

-1, 223, 

137, 37 

8 


LTEXT 

"Flags", 

-1, 283, 

137, 26 

8 


LISTBOX 

IDL MEMLIST, 5, 22, 208, 114, 

WS_ 

GROUP 


! WS TABSTOP 




DEFPUSHBUTTON 

"Allocate", 

IDB_ALLOCATE, 4, 

4, 

50, 14 


WS_GROUP | 

WS_TABSTOP 




PUSHBUTTON 

"Free", 

IDB_FREE, 

57, 

4, 

50, 14 


WS TABSTOP 





LISTBOX 

IDL_PAGELIST, 222, 22, 

102, 114, 



WS GROUP ! 

WS_TABSTOP 

| LSJ/IULTIPLESEL 


| LS_EXTENDEDSEL 




PUSHBUTTON 

"Select", 

IDB_SELECT 

, 171 , 

4, 

50, 14 


WS_GROUP | 

WS_TABSTOP 




PUSHBUTTON 

"State", 

IDB_STATE, 

224, 

4, 

50, 14 


WS_TABSTOP 





PUSHBUTTON 

"Rights", 

IDB_RIGHTS 

, 277, 

4, 

50, 14 


WS TABSTOP 






MEMORY.DEF 


NAME 

DESCRIPTION 

PROTMODE 

HEAPSIZE 

STACKSIZE 

EXPORTS 


MEMORY WINDOWAPI 

'Memory Program (c) Blain, Delimon, & English, 

4096 

16384 

MainDlgProc 

AllocateDlgProc 
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Using the MEMORY Sample Application 

The MEMORY application demonstrates committing, freeing, and changing the access 
rights to blocks of memory. Its use is also fairly explanatory. Remember though that you 
are making the changes only within a block of memory that is available to the MEMORY 
application. After starting the memory application, press the allocate button to allocate 
blocks of memory. The display for the allocated memory will appear similar to that shown 
in Figure 9.6. 


Figure 9.6. 

MEMORY application. 



Practice allocating both committed and uncommitted blocks of memory. Notice what 
state a particular block of memory must be in before its access rights can be changed. 
Notice also that the successive addresses for committed blocks of memory that are not 
shared grow upward. Addresses for successive blocks of shared memory grow downward. 
This behavior is in keeping with how these blocks of memory are allocated by the 
system. 

Understanding MEMORY’S Code 

Two macros will be used to set our current pointer. When we begin a time-consuming 
process, we will set the pointer to the SPTRJ/VAIT pointer and, when done, reset it to the 
SPTR_ARROW pointer: 

#define WAIT_POINTER WinSetPointer (HWND_DESKTOP, \ 

WinQuerySysPointer 
(HWND_DESKTOP,SPTR_WAIT,FALSE)); 

#define ARR0W_P0INTER WinSetPointer (HWNDJ3ESKT0P, \ 

WinQuerySysPointer 
(HWND_DESKTOP,SPTR_ARROW,FALSE)); 
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The CenterWindow function merely centers the dialog in the middle of the screen: 

VOID CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd,&Rectl); 

WinSetWindowPos (hWnd, HWND_T0P, (ulScrWidth- Recti.xRight) /2, 

(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_M0VE \ SWP_ACTIVATE); 

return; 


To format our memory list items in the list box, the FormatMemListltem function 
takes the memory address, amount of memory originally requested, amount of memory 
actually allocated, and amount of memory currently committed and formats them using 
the sprintf function: 

PSZ FormatMemListltem (PVOID pMem, LONG lAllocRequest, 

ULONG ulAllocated, ULONG ulCommitted) 

{ 

sprintf (szListltem,"%081x %81x %81x %81x", 

(ULONG)pMem, (ULONG)lAllocRequest, ulAllocated, ulCommitted); 
WinUpper (hab, 0, 0, szListltem); 
return (szListltem); 


Likewise, the FormatPageListltem function takes the memory address and current 
page flags and formats them using the sprintf function. The memory page flags are 
checked individually and set in the string: 

PSZ FormatPageListltem (PVOID pMem, ULONG ulFlags) 

{ 

sprintf (szPageltem, "%081x ", pMem); 

szPageItem[9] = (CHAR)(ulFlags & PAG_READ ? 'R' : 1 '); 

szPageItem[10] = (CHAR)(ulFlags & PAGJVRITE ? 'W 1 : ' '); 

szPageltem[11] = (CHAR)(ulFlags & PAG_EXECUTE ? 'E 1 : 1 '); 

szPageItem[12] = (CHAR)(ulFlags & PAG_COMMIT ? 'C' : ' '); 

szPageItem[13] = (CHAR)(ulFlags & PAG_SHARED ? 'S' : 1 '); 

WinUpper (hab, 0, 0, szPageltem); 
return (szPageltem); 


The MemError function is merely a consistent way for us to output our error mes¬ 
sages using the WinMessageBox function: 

VOID MemError (PSZ pszMessage) 

{ 

WinMessageBox (HWND_DESKTOP, hWndFrame, pszMessage, 

"Memory Allocation", 0, MB_ERR0R | MB_OK); 
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return; 

} 

When a list box item is selected, we need to determine what memory address has 
been selected. Because each list box item is formatted as a string, the Parseltem func¬ 
tion can be used to convert any portion of a string from its hexadecimal string value to an 
equivalent binary value. The first parameter szItem is the string to be parsed. The sec¬ 
ond parameter CurPos is the offset in szltem to start the conversion. The maximum 
size of our hexadecimal substrings is eight characters, so we look at the eight characters 
starting at position CurPos: 

ULONG Parseltem (PSZ szltem, ULONG CurPos) 

{ 

ULONG EndPos = CurPos + 8; 

ULONG ulMem = 0; 

for (; CurPos < EndPos; CurPos++) 

{ 

if (szItem[CurPos] != 1 ') 
ulMem = ulMem*16 + 

((szItem[CurPos] <= '9') ? (szItem[CurPos] - '0') : 

(szItem[CurPos] - 'A' + 10)); 

} 

return (ulMem); 

} 

The ChangeAccessRights function is used to set the access rights of the selected 
memory pages. The only parameter to this function is the new access rights to be set. 
Our menu items have conveniently been defined such that the low byte of their identi¬ 
fier is the new access rights, so we can just AND this identifier with 0x0007 to get the 
new access rights. We then loop, querying the next selected item in the memory page list 
until there are no more selected. Querying the text for each item, we call Parseltem to 
retrieve the memory address for the selected page. The call to DosSetMem will attempt to 
set the access rights of the page. Because we can change the access rights only for a com¬ 
mitted page, the DosSetMem call will fail if the page is not committed. If the DosSetMem 
call is successful, we query the access rights of the page and reformat the item to be up¬ 
dated in the list box. It is necessary to query the memory again because decommitting a 
page will reset the access rights to those defined when the memory was allocated. 

The ChangeCommitState function is used either to commit or decommit the selected 
memory pages. The only parameter is a flag indicating if the memory is to be committed 
or decommitted. Because the list box text for the memory list box has already been re¬ 
trieved in QueryMemory, we can just call Parseltem on szListltem to get the current 
amount of committed memory for the selected item. This enables us to update the amount 
of committed memory as we make the updates. 

We then loop, querying the next selected item in the memory page list until there are 
no more selected. Querying the text for each item, we call Parseltem to retrieve the 
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memory address for the selected page. Because we want to leave the access rights unchanged 
for the page, if we are committing memory, we must set the access rights to their current 
settings. We can either call DosQueryMem to get them or look at the current flags in the 
list box string. The call to DosSetMem will attempt to commit or decommit the page. If 
the call to DosSetMem is successful, we query the memory to get its new flags. When a 
page is decommitted, its access rights are reset to those defined when the memory was 
allocated. We then update the amount of committed memory. When all selected pages 
have been processed, we must update the amount of committed memory in the memory 
list box. 

The QueryMemory function is used to retrieve the current flags for each page of memory 
for each allocated memory object. The input to this function is the index in the list box 
of the selected memory object. We begin by querying the text for the selected item and 
deleting all the items in the page list box. The call to WinEnableWindowUpdate tells PM 
not to repaint the list box as we are making our updates. This prevents the window from 
repainting every time we add a new item. When we are done, we will reenable the paint¬ 
ing of the list box. 

The call toParseltem converts the address portion of the string, so we have the base 
address for the memory object. We then repeatedly make calls to DosQueryMem to query 
the memory flags. Remember, if the address queried is the first page of a memory object, 
the PAG_BASE flag is set. If the page is not currently allocated, the PAG_FREE flag is set. 
Also, the DosQueryMem call will query pages until it finds a page with a different memory 
flag than the first page queried or it finds the first page of the next allocated memory 
object. Our loop will, thus, repeat until we either reach the end of the currently allocated 
object (PAG_FREE) or we reach the beginning of the next allocated memory object 
(PAG_BASE). We want to ignore the check for PAG_BASE on the first page because it will 
have the PAG_BASE flag set. 

Each call to DosQueryMem will start at the address in ulAddress and return the size 
of the memory pages that have the same flags as the first page at ulAddress. The ul Flags 
variable will contain those flags. Our total allocated count can be incremented by ulSize, 
and ulCommitted is incremented if the PAG_COMMIT flag is set. We then add a page entry 
to the pages list box for each page in the queried memory. When the memory object has 
been completely queried, we reenable the list box updates and select the first item in the 
list box. We also update the allocated and committed totals in the memory list box. 

AllocateDlgProc is the dialog function for the memory allocation dialog. When 
we receive the WM_INITDLG message, we can initialize all the controls in the dialog win¬ 
dow. Because we save the last settings of each button from the last time the dialog was 
displayed, we use those values to either check or uncheck the buttons. Our spinners are 
initialized for their size, limits, and current value. Our dialog enables you to specify the 
amount of memory to allocate and its access rights, whether to commit the memory when 
it is allocated, whether it is private or shared memory, and whether it should be allocated 
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out of the tiled arena. We also have the ability to repeat the memory request up to 9,999 
times. When the WM_COMMAND message is received with the OK button pressed, we query 
the values input and current state of the buttons. Then, for each memory allocation 
request (the repeat count), we make the call to either DosAllocMem (private memory 
allocation) or DosAllocSharedMem (shared memory allocation). If the allocation is 
successful, we add an entry to the memory list box and call QueryMemory to fill the pages 
list box. When all memory requests have been made, we exit the dialog. 

MainDlgProc is the dialog function for the main dialog of this program. When we 
receive the WM_INITDLG message, we query the handles and set the font for our two list 
boxes. We set the font to a monospaced font so that the columns in the list box align 
properly. The four different pop-up menus are also loaded at this time. If we receive a 
WM_C0NTR0L message from the memory list box and an item has been selected, we call 
QueryMemory to update the pages list box with the pages for the selected memory object. 
We receive a WM_COMMAND message for each button pressed in the dialog. If the command 
is IDB_ALLOCATE, we display the memory allocation dialog. If the command is IDB_SELECT, 
IDB_FREE, IDB_STATE, or IDB_RIGHTS, we display the pop-up menu directly above the 
button. The identifiers for the buttons and menus are the same. If IDM_SELECT_NONE 
is selected, we send the LM_SELECTITEM message to the pages list box with LIT_N0NE 
specified so that no items are selected. If IDM_SELECT_ALL is selected, we send the 
LM_S ELECT ITEM message to the pages list box for each item in the list box. If one of the 
commit options is selected, we call ChangeCommitState. If one of the access rights op¬ 
tions is selected, we call ChangeAccessRights. If IDM_FREE_SELECTED is selected, we 
call DosFreeMem on the selected memory object and remove it from the list box. After 
deleting the item, we select a new item. If IDM_FREE_ALL is selected, we call DosFreeMem 
on each item in the list box and remove it from the list box. 
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What Is a DLL and How Docs It Work? 

Dynamic Link Libraries (DLLs) form the foundation of OS/2. They provide the key 
components in making OS/2 and the Presentation Manager (PM) work with your appli¬ 
cation. The DLL’s importance to OS/2 is shown in that most of OS/2 and the 
Presentation Manager are implemented as DLLs. This chapter focuses on this 
important feature of OS/2 and demonstrates how to take advantage of 
the power it provides. 

If 
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A DLL is a collection of code and/or resources maintained in a separate executable- 
like file that can be used by your application. A DLL, however, is not executable: It can¬ 
not be run by itself, but its functions and resources can be used by applications linked to 
it. You can think of a DLL as an extension of your application, but it also can be shared 
by multiple processes. 

The concept of DLLs must not to be confused with processes or threads, which are 
entirely separate, unrelated mechanisms. Using a DLL does not make your application 
multithreaded. A DLL is an extension of your application; it is extra code. The code in a 
DLL executes on behalf of your process, but the activity in that DLL is still single threaded, 
unless it is explicitly defined otherwise by you, the programmer. 

Most programmers are already familiar with static linking. Static linking occurs when 
you link your application with an external library of code. In static linking, the library 
actually contains the object code implementing the functions in the library. When you 
link your application with a static library, the required object code is pulled into your 
executable and becomes part of the executable file. Every application linked to a particu¬ 
lar static library has its own copy of the same object code. The same object code, thus, is 
replicated for every application and takes up additional disk space. When the application 
is executed, the same object code is replicated in memory, taking up space each time. 
This is just one of the problems of static linking. Another problem is that if the library 
needs to be updated to correct a problem in the code or to add new logic to a function, 
every application linked to the library must be relinked and redistributed. 

Herein lies the beauty of DLLs. A DLL provides services to your application much 
like a static library does, but can be replaced or updated without changing or updating 
your application. In addition, because multiple processes can share the code of a DLL, 
the amount of disk space and memory required for a program to run is reduced. The 
library created for a DLL is called an import library. This is a smaller file which has an 
extension of LIB. It contains no code, but does contain information about the names of 
the functions in the library and the necessary information to complete the linking pro¬ 
cess. The object code resides in a separate DLL file. When the application is loaded into 
memory, the OS/2 loader loads the DLL into memory (if it isn’t already in memory) and 
resolves the addresses of the calls into the DLL with the actual addresses. 

The obvious benefit here is that a DLL can be updated and replaced on the system. 
Then, all applications immediately have the latest code executing from the DLL. You 
can also add new functions to the DLL, allowing new applications to call these functions 
without disturbing the existing applications that are using the DLL. 
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It may help to take a look at the process of static linking and compare it with dy¬ 
namic linking. First, take a look at static linking as pictured in Figure 10.1. In creating 
an application, assume we are making some external calls into a static library. Although 
the concept is the same for any static library, we will use the C functions strcpy and 
strcmp as examples. In compiling our application, whenever a call to an external func¬ 
tion is identified, the compiler inserts a record in the file describing the name of the func¬ 
tion to call. Because it does not know the address of the function, the record contains an 
unresolved reference. 

Figure 10.1. 

An application object Unresolved symbols 

module. 

Application code 


Application Object Module 


1 1 

00 w 

o o 
q T3 
-a ^ 

CALL _ 

;_strcpy 

CALL _ 

;_strcmp 

CALL _ 

;_strcmp 


Taking a look at the static library, we can see that the object code for the functions in 
the library is contained within the library (see Figure 10.2). 


Figure 10.2. 

A static library file. 


Static Library 


Public Symbols 

stripy 




strcmp 

— 

—1 

Object code 

Code for strcpy 

i 

i 



Code for strcmp \ _| 

__:_ i 


During the linking process, the linker will look at the unresolved symbols in the ap¬ 
plication object module and search for those symbols in the libraries that it is linked to. 
When the linker locates a match, it resolves the symbol by copying the object code from 
the library into the executable file being constructed. The address of the function is then 
known, and all references to the external function are set to the new address of the func¬ 
tion (see Figure 10.3). 
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Figure 10.3. 
Executable file with 
resolved symbol 
addresses. 


Application Executable 

Executable Header 
Code Segment 


Offset 329C 

Offset 3520 


CALL 329C ;_strcpy 
CALL 3520 ;_strcmp 
CALL 3520 ;_strcmp 


code for _strcpy 


code for _strcmp 


The offsets shown are only arbitrary offsets and will depend on the actual size of 
the code. At this point, the executable is complete, and all the code is literally contained 
within it. 

Compare this with dynamic linking. We will use our application object module shown 
previously. Let’s assume we now have created a DLL that contains code for the strcpy 
and st rcmp functions. This time, we use the import library created for the DLL (see Fig- 


ure 10.4). 


Figure 10.4. 

Import Library 

, . DLL Object Records 

An import library. 


Exported Name 

strcpy 

DLL Name 

MYLIB.DLL 

Ordinal 

1 

Internal Name 

_strcpy 

Exported Name 

strcmp 

DLL Name 

MYLIB.DLL 

Ordinal 

2 

Internal Name 

_strcmp 


Notice that the import library contains no code. It does contain three items for each 
exported function: the name of the exported function, the name of the DLL containing 
the function, and the entry point for the function. The entry point can be either an or¬ 
dinal or the internal name of the function or both. We will look at how these entries are 
created in the next section. During the linking process, the linker will look at the un¬ 
resolved symbols in the application object module and search for those symbols in the 
libraries that it is linked to. When the linker locates a match this time, it resolves the 
symbol by inserting a relocation record into the executable (see Figure 10.5). 
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Application Executable 

Executable Header 

Code Segment 
Offset 24F0 

Offset 2720 

Offset 29E4 

Relocation Records 

First offset 
DLL Name 
Entry point 


First offset 
DLL Name 
Entry point 


The offsets shown are only arbitrary offsets and will depend on the actual size of the 
code. Each relocation record contains the offset of the first call to the function in the 
DLL. The instruction at that offset in the executable contains one of two values. If there 
is more than one call to the exported function, the instruction at that offset contains a 
CALL instruction with the address portion containing the offset of the next call to the 
same exported function. If the instruction at that offset is the last call in the application 
to that function, it contains a “CALL FFFF” instruction. Essentially, the linker has cre¬ 
ated a linked list of calls to each function that resides in a DLL. 

At this point, the executable is complete, but where is the code for our external func¬ 
tions? The code is contained within the DLL. When the program is executed, the OS/2 
loader attempts to resolve all the calls into the DLL. It does this by examining the relo¬ 
cation records in the application executable. After ensuring the DLL is loaded into 
memory, the OS/2 loader locates the appropriate entry in the DLL’s entry table. With 
the actual address of the function in hand, it then walks the linked list of calls in the 
application and inserts this address (see Figure 10.6). 

When a DLL is loaded, it is possible that the DLL itself is linked to other DLLs. The 
OS/2 loader performs the same process on the DLL as it does for the executable. It loads 
all necessary DLLs and resolves the addresses before attempting to resolve the addresses 
of the executable. 

We just looked at one way a DLL is loaded into memory and how its exported func¬ 
tion calls are resolved. There are actually several ways a DLL can be loaded into memory 
and its functions called. We will examine all the variations later in this chapter. 


CALL FFFF ;_strcpy 
CALL29E4 ;_strcmp 
CALL FFFF ;_strcmp 


24F0 

MYLIB.DLL 
1 (or) _strcpy 


2720 

MYLIB.DLL 
2 (or) _strcmp 


Figure 10.5. 
Executable file with 
DLL references. 
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Figure 10.6. 

An application 
executable file and DLL 
demonstrating address 
references. 


Executable Header 
Code Segment 
Offset 7FCA 

Offset 821E 

Application Executable 

Executable Header 
Code Segment 
Offset 24F0 

Offset 2720 

Offset 29E4 


CALL 7FCA ; _strcpy 
CALL 821E ; _strcmp 
CALL 821E ; _strcmp 


MYLIB.DLL 


code for _strcpy 


code for _strcmp 


How to Build a DLL 

The purpose of a DLL is to provide code or resources that can be utilized by more than 
one process. For example, we could take the code from Chapter 3, Window Manage¬ 
ment,” that arranged child windows in various ways and put it into a DLL for all our 
applications to use. You may now be asking, “How do I create my own DLL?” In this 
section, we will show you how to do just that. We will begin by creating a basic DLL that 
contains two functions. We will use the CenterWindow function from the MINIMDI 
application, plus a function to fill a window with a specified color. In general, functions 
that could reside in an application can be placed into a DLL. 

The components for building a DLL are the same as for an application. The main 
difference is in how the DLL is constructed. Those familiar with building 16-bit DLLs 
will notice it is no longer necessary to worry about DS != SS. Only one data and code 
segment exists for a 32-bit machine, and DS is always equal to SS. 

The first step in building our DLL is to create the C file containing the code. 

DLLSAMP.C 


/* 


DLLSAMP Program 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


#define INCL_WIN 
#define INCL_GPI 


. 

430 

i- 
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#include <os2.h> 

#include "dllsamp.h" 

VOID EXPENTRY CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd, &Rectl); 

WinSetWindowPos (hWnd, HWND_T0P, (ulScrWidth-Recti.xRight)/2, 

(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_M0VE | SWP_ACTIVATE); 
return; 


VOID EXPENTRY FillWindow (HWND hWnd, HPS hps, ULONG ulRGB) 

{ 

RECTL Recti; 

BOOL bRelease = FALSE; 

if (!hps) 

{ 

hps = WinBeginPaint (hWnd, 0, 0); 
bRelease = TRUE; 

} 

WinQueryWindowRect (hWnd, &Rectl); 

/* Set color state in the hps to RGB mode */ 

GpiCreateLogColorTable (hps, LCOL_RESET, LCOLF_RGB, 0L, 0L, NULL); 
WinFillRect (hps, &Rectl, ulRGB); 
if (bRelease) 

WinEndPaint (hps); 
return; 


Because a DLL is not an executable, there is no main () function. We did not define 
local functions here, but there is no restriction on doing so. For now, we have not de¬ 
fined global variables in this DLL. We will look at that part of DLLs later. All functions 
to be exported from a DLL should be defined with the EXPENTRY keyword. EXPENTRY 
defines the calling convention for the function to be a system call (_syscall or 
_System). 

The file dllsamp.h contains the function prototypes for our exported functions so 
that applications or other DLLs wanting to use this DLL can include dllsamp.h to get 
these prototypes. 
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DLLSAMP.H 

/* Exported Functions */ 

VOID EXPENTRY CenterWindow (HWND); 

VOID EXPENTRY FillWindow (HWND, HPS, ULONG); 

We can now compile this file just as we would for an executable producing our 
DLLSAMP.OBJ file. The key component in creating a DLL is the DEF file. The DEF 
file specifies that we are creating a DLL, and defines all the exported functions and how 
the data segments are assigned. Let’s examine the format of the DEF file for our DLL. 

DLLSAMP.DEF 

LIBRARY DLLSAMP 

DESCRIPTION 'DLL Sample 1993 Blain, Delimon, & English' 

DATA SINGLE 
EXPORTS 

CenterWindow @1 
FillWindow @2 

The first line contains the keyword “LIBRARY” rather than “NAME.” The format of 
the LIBRARY statement is as follows: 

LIBRARY [modulename] [module initialization] 

modulename Name of the DLL. 

module initialization 

INITGLOBAL Initialization code is called 

only hen the DLL is first 
loaded (default). 

INITINSTANCE Initialization code is called for 

each process that loads the 
DLL. 

The LIBRARY keyword tells the linker that it should create a DLL rather than an ex¬ 
ecutable. After the keyword, LIBRARY is the name of the DLL. If the modulename is not 
specified, the name of the filename is used. Do not worry about the module initialization 
statement at this point as it will be discussed shortly. 

The DATA statement defines the default characteristics of the data segments. Its for¬ 
mat is as follows: 


V 
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DATA [loadtype] [access] [DGROUP type] [shareability] [privilege] 


loadtype 


DGROUP type 


shareability 


privilege 


PRELOAD 

Load data segment when 
DLL is loaded. For OS/2 
2.0 and later, this 
keyword is ignored. 

LOADONCALL 

Load data segment on 
first access (default). 

READONLY 

Data segment can be read 
but not written. 

READWRITE 

Data segment can be read 
and written (default). 

NONE 

There is no DGROUP. 

SINGLE 

All instances of the DLL 
share the DGROUP 
(default). 

MULTIPLE 

Each instance of the DLL 
has its own DGROUP. 

SHARED 

Data segment is shared 
among all instances of the 
DLL (default). 

NONSHARED 

Data segment is private to 
each instance. 

IOPL 

Data segment can be 
accessed only from ring 2. 

NOIOPL 

Data segment can be 
accessed by ring 2 or ring 

3 (default). 


The DGROUP type and shareability are integrally related. If SINGLE is specified, 
SHARED is assumed. If MULTIPLE is specified, NONSHARED is assumed. Likewise, if SHARED 
is specified, SINGLE is assumed. If MULTIPLE is specified, NONSHARED is assumed. The 
DATA statement will become important when we discuss instance and global data seg¬ 
ments. For now, we are safe to use DATA SINGLE because we do not really have any data 
in our DLL. 


Next, we specify the functions that will be exported by our DLL. This is done with 
the EXPORTS statement: 
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EXPORTS 

export statement 
export statement 

Each export statement can have one of several formats. In general, it uses the follow¬ 
ing format: 

exported name [= internal name] [^ordinal] 

exported name The name of the function known outside of the DLL. 

internal name The name of the function known internally to the DLL. 

@ordinal Number assigned to the entry. 

The simplest way to export a function is to list the function name: 

EXPORTS CenterWindow 

Alternatively, if we want the outside world to know the function by a different name, 
we can assign a different exported name and map it to the internal name: 

EXPORTS Center = CenterWindow 

In this example, all applications and other DLLs would call the function by its ex¬ 
ported name, Center. The linker would map those calls to the CenterWindow function. 
The Oordinal part is also an optional parameter. We can assign any ordinal number to 
our functions to speed the dynamic linking process. If we do not supply an ordinal, when 
the OS/2 loader is trying to match the function names in the application with those in 
the DLL, it must search for each function by name. 

On the other hand, if there is an ordinal specified for the functions, the linker builds 
a table of functions indexed by their ordinal. The OS/2 loader, therefore, needs to look 
up the entry only by its index into this table. If you use ordinals, it is best to start at 1 and 
make them sequential. All ordinals must be unique within a DLL. 

There is one caveat to using ordinals. Earlier, we talked about how you could replace 
a DLL on a system with a new one and have existing applications that utilize the DLL 
immediately use the new DLL. Remember also that the OS/2 loader matched the reloca¬ 
tion records with the entries in the DLL’s entry table. Without ordinals, the OS/2 loader 
does this matching by name, so as long as the exported function names remain the same 
in the new DLL, there is no problem. If, however, ordinals are specified, the relocation 
records reference the DLL entry by ordinal, not by name. Therefore, if you change the 
ordinal value for any function in the new DLL, the OS/2 loader will match that reloca¬ 
tion record with whatever function now has that ordinal—potentially, a troublesome 
situation because the wrong function will be called. For this reason, it is best to delay 
using ordinals until the DLL is complete, and, once the ordinals are defined, do not re¬ 
assign them. 
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To define an ordinal we would use the following: 

EXPORTS CenterWindow @1 

We could also redefine the function name and assign an ordinal, as follows: 
EXPORTS Center = CenterWindow @1 

It is also possible to export variables. Variables can be exported using the same syntax 
as exported functions: 

_DLLCount @400 

This exports the global DLL variable _DLLCount. An application can reference this 
variable by defining it as an external variable. 

You may be wondering why there is no STACK keyword in the DEF file for a DLL. 
The STACK keyword is not relevant to DLL because DLLs do not have a stack. They use 
the same stack as the application. In other words, they share the application’s stack. 

We can now link our object file to create the DLL. Remember to link to the DLL 
version of your compiler’s library. Our DLL is now created. The only thing left to do is 
to create the import library so that other modules can link to the DLL. To create the 
import library, we use the IMPLIB command: 

IMPLIB DLLSAMP.LIB DLLSAMP.DEF 

The IMPLIB command takes the DEF file and creates an import library based on those 
functions specified in the EXPORTS statement. The DLLSAMP.LIB library created from 
this is then used to link to other modules. 

With the renaming capabilities of the EXPORTS statement, we can use a little trick to 
override any function defined by another library. For example, if we want to define some 
alternative to the PM function WinCreateStdWindow, we could define our own func¬ 
tion MyWinCreateStdWindow that may do something in addition to calling 
WinCreateStdWindow. We would export our function as follows: 

EXPORTS Win32CreateStdWindow = MyWinCreateStdWindow 

The function name is actually Win32CreateStdWindow because the PMWIN.H header 
file defines WinCreateStdWindow to be Win32CreateStdWindow. After creating our import 
library, all we must do is ensure that our library is linked before the OS2386 library. The 
linker uses our Win32CreateStdWindow call rather than the OS2386 library. Our DLL 
is still free to call the original Win32CreateStdWindow, because it will link with OS2386 
and its call will go directly to PM. 

Although you may not want to rename PM functions often, this capability is useful 
for maintaining backward compatibility for DLLs that you may be distributing or using 
for your application. Let’s say you have a function called DoSomeWork that currently de¬ 
fines two parameters and is exported with an ordinal: 
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VOID EXPENTRY DoSomeWork (BOOL bParml, BOOL bParm2) 

EXPORTS DoSomeWork @10 

Imagine that at some future point, you decide you need an additional parameter to 
this function. You have a problem because applications currently using this library will 
be passing only two parameters. Here are some steps to follow to make this work without 
breaking existing applications. 

1. Make the changes to the function DoSomeWork: 

VOID EXPENTRY DoSomeWork (BOOL bParml, BOOL bParm2, BOOL bParm3) 

2. Define a stub function that takes the original two parameters and calls the new 
function with some default value for the third parameter: 

VOID EXPENTRY DoSomeWork2 (BOOL bParml, BOOL bParm2) 

{ 

DoSomeWork (bParml, bParm2, FALSE); 

} 

3. Use the ranaming capabilities of the EXPORTS statement to remap the ordinal to 
the stub function: 

EXPORTS DoSomeWork2 @10 
DoSomeWork @11 

All existing calls to the old DoSomeWork function still reference ordinal 10 that now 
will call the stub function. All new applications will call the modified DoSomeWork func¬ 
tion at ordinal 11. 

With our DLLSAMP.DLL built, we can call it from our application. The APPSAMP 
application simply makes calls into the DLLSAMP dynamic link library. The files for 
building APPSAMP are as follows: 

APPSAMP.DEF 
APPSAMP.RC 
APPSAMP.H 
APPSAMP.C 
APPSAMP.ICO 

APPSAMP.H 

/* 

APPSAMP Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 
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#define 

ID_APPNAME 

1 

#define 

IDM_ 

DC 

O 

—I 

o 

o 

1 

100 

#define 

IDM_ 

RED 

101 

#define 

idm" 

_GREEN 

102 

#define 

i dm" 

BLUE 

103 

#define 

idm_ 

CENTER 

200 

#define 

idm 

ABOUT 

300 


APPSAMP.RC 


/* 


APPSAMP Resource File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "appsamp.h" 

/* Icons */ 

ICON ID_APPNAME APPSAMP.ICO 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "DLL Sample Application (Implicit Load)" 

END 

MENU ID_APPNAME 

{ 

SUBMENU "-Color", 

{ 

MENUITEM "-Red", 

MENUITEM "-Green", 

MENUITEM "-Blue", 

} 

MENUITEM "Cen-ter", 

MENUITEM 

MENUITEM "-About", 


IDM_C0L0R 

IDM_RED 

IDM_GREEN 

IDM_BLUE 

IDM_CENTER 

-1, MIS_SEPARAT0R 

IDM ABOUT 


rcinclude ..\..\common\about.dig 
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APPSAMF.C 


/* 


APPSAMP Program 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 

#include <os2.h> 

#include "appsamp.h" 

#include "dllsamp.h" 

#include "..\.\common\about.h" 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 

HAB hab; 

HWND hWndFrame = 0, 
hWndClient; 

CHAR szTitle[64]; 

ULONG ulColors[3] = { 0X00FF0000, 0X0000FF00, 0X000000FF }; 
ULONG ulCurrentColor = 0L; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | FCF_MENU [ 

FCF_SIZEBORDER | FCF_MINMAX | FCF_ICON | 
FCF_SHELLPOSITION | FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
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return (0); 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

HPS hps; 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_PAINT: 

hps = WinBeginPaint (hWnd 3 0 3 0); 

/* Call DLL function to fill the window */ 

FillWindow (hWnd, hps 3 ulColors[ulCurrentColor]); 

WinEndPaint (hps); 

break; 

case WM_ERASEBACKGROUND: 
mReturn = MRFROMLONG(1L); 
break; 

case WM__COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_RED: 
case IDM_GREEN: 
case IDM_BLUE: 

ulCurrentColor = LOUSHORT(mp1) - IDM_RED; 
hps = WinGetPS (hWnd); 

/* Call DLL function to fill the window */ 

FillWindow (hWnd, hps, ulColors[ulCurrentColor]); 

WinReleasePS (hps); 

break; 

case IDM_CENTER: 

/* Call DLL function to center the window */ 

CenterWindow (hWndFrame);22 

break; 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 
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if (IbHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


Our calls to CenterWindow and FillWindow are resolved by linking with the 
DLLSAMP.LIB import library. When APPSAMP is executed, the OS/2 loader will au¬ 
tomatically load the DLLSAMP.DLL for us and handle the resolution of our function 
calls into the DLL. THe APPSAMP application window is shown in Figure 10.7. 


Figure 10.7. 

The APPSAMP 
primary window. 



In our example, we used the library DLLSAMP.LIB to identify the functions that we 
used. In addition, we are resolved to using the names of the functions as they are defined 
in DLLSAMP.LIB. This process of using functions in a DLL is sometimes referred to as 
importing a function. The library does the importing for us automatically. It is possible 
to import functions from a DLL even without having a library file for the DLL. How¬ 
ever, in either case, only functions exported from a DLL can be imported. This is done 
by using the IMPORTS statement in the DEF file for the application or DLL: 

IMPORTS 

import statement 
import statement 

The format of the IMPORTS statement is similar to the EXPORTS statement. In gen¬ 
eral, it uses the following format: 

[imported name =] DLLname.exported name | DLLname.ordinal 

imported name Name of the function used in the application. 

DLLname Name of the DLL. 
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exportedname Name of the function exported from the 

DLL. 

ordinal Ordinal of the function exported from the 

DLL. 

Use of the ordinal is only valid if the exported function has been exported with an 
ordinal. The simplest way to import a function is to list the function name: 

IMPORTS DLLSAMP.CenterWindow 

Alternatively, to assign a different name for the function to be used by our applica¬ 
tion, we could map the function using the following: 

IMPORTS Center = DLLSAMP.CenterWindow 

To use the ordinal, we must assign a name to the function as it is used within the 
application. It may or may not be the same name as the function name in the DLL: 

IMPORTS CenterWindow = DLLSAMP.1 

Just as we showed how a DLL can intercept the function call to WinCreateStdWindow, 
we can do the same to redirect our function call to a function within a DLL: 

IMPORTS Win32CreateStdWindow = DLLSAMP.MyCreateStdWindow 

This remaps all calls to Win32CreateStdWindow to the MyCreateStdWindow func¬ 
tion in the DLLSAJMP.DLL. 

What do you do in this situation: You are linking two different import libraries; both 
use the same function name, and you want to use both functions. The linker will use the 
function it finds in the first import library specified during the linking process. You can 
use the IMPORTS statement to alias the two functions. If the function is FillWindow, we 
could define it as follows: 

IMPORTS 

LiblFillWindow = LIB1.FillWindow 
Lib2FillWindow = LIB2.FillWindow 

When we want to call the FillWindow function of the LIB 1 DLL, we would call it as 
Libl FillWindow (). To call the FillWindow function of the LIB2.DLL, we would call 
it as Lib2FillWindow. 


The LIBPATH Statement 

Before we get too much farther, it is worth pausing for a minute and discussing how 
OS/2 finds the DLL to load. When dynamic linking is involved, OS/2 uses the LIBPATH 
statement in your CONFIG.SYS file to search for the DLL. After a quick check of the 
DLLs already in memory, the OS/2 loader will search for the DLL using the LIBPATH 
statement. It is usually a good idea to include the current directory somewhere in the 
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LIBPATH because most applications do not install their DLLs in a common DLL direc¬ 
tory, but in the same directory as the executable: 

LIBPATH=.;C:\0S2\DLL;C:\BIN\0S2;D:\TOOLKT20\BIN 

The LIBPATH is not always used in the search. If the application attempts to load a 
DLL using runtime dynamic linking, it may not use the LIBPATH depending on how the 
name of the DLL is specified. We look at runtime dynamic linking next. 

Runtime Dynamic Linking 

The dynamic linking we have discussed so far is referred to as load-time dynamic link¬ 
ing. With load-time dynamic linking, the names of the DLLs linked against the applica¬ 
tion are specified at link time, and at load time, the system automatically searches for and 
loads these DLLs. This process is automatic; the application may even be unaware this is 
occurring. Load-time dynamic linking forces the DLL to be loaded into memory when 
the application is loaded. The DLL occupies memory in the system until the application 
terminates. If the functions in the DLL are used frequently, including during initializa¬ 
tion, this is an appropriate method; however, what if we need to call into the DLL only 
under certain conditions? The DLL would be loaded the entire time and would be re¬ 
serving a certain amount of our shared memory addresses. What if we have multiple ver¬ 
sions of a DLL, and we want to use a different one depending on the screen resolution? 
We wouldn’t want all versions of the DLL to be linked with the application when we 
need only one of them. 

The solution is runtime dynamic linking. With runtime dynamic linking, the DLL 
is explicitly loaded and unloaded by the application when it requires the DLL’s code. 
The addresses of the functions to call are also retrieved as needed. The DLL, thus, is only 
in memory when it is required, and it is possible to selectively load a particular DLL. 

Runtime dynamic linking is performed with the use of three functions: 
DosLoadModule, DosQueryProcAddress, and DosFreeModule. DosLoadModule is used 
to load the DLL into memory: 

AIPIRET APIENTRY DosLoadModule(PSZ pszName, ULONG cbName, PSZ 
pszModname, PHMODULE phmod); 

pszName 

cbName 
pszModname 
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Buffer to return name of module that caused 
failure to load. 

Size of pszName. 

The name of the DLL to load. If the 
LIBPATH is to be searched, this should be 
the name of the DLL without the DLL 
extension. Otherwise, this should be the 
full path of the DLL including the DLL 
extension. 
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phmod 


Address of the module handle of the loaded 
DLL. 


If the DLL is already loaded, DosLoadModule will return the handle to the DLL. If 
the DLL is not found or it is unable to load, a nonzero return code will be returned. 

With the DLL loaded, we can use the module handle returned from DosLoadModule 
to query the addresses of the functions we want to call. DosQueryProcAddr is used to do 
this: 


APIRET APIENTRY DosQueryProcAddr(HMODULE hmod, ULONG ordinal, PSZ 
pszName, PFN* ppfn); 

hmod Module handle of the DLL. 

ordinal Ordinal number of function to retrieve 

address. If this value is zero, the function is 
retrieved by name. 

pszName Name of function to retrieve address. This 

parameter is ignored if a nonzero ordinal is 
specified. 

ppfn Address to copy function address. 

If the function is located in the DLL, the address of the function is returned in the 
variable referenced by ppf n. Otherwise, a nonzero return code is returned. Notice that it 
is possible to receive a nonzero return code when the function exists and the DLL is loaded 
in memory. OS/2 requires that DosLoadModule must be called at least once for a DLL to 
retrieve a function address with DosQueryProcAddr. This is true even if the DLL is loaded 
for the process by using load-time dynamic linking. If you receive the return code of 
ERROR_INVALID_HANDLE, you must call DosLoadModule, which will return the handle 
again and then reissue the call to DosQueryProcAddr. 

When you are finished with the DLL and want to free it from memory, use the 
DosFreeModule function: 


APIRET APIENTRY DosFreeModule(HMODULE hmod); 

hmod Module handle of the DLL to free. 

If the DLL was initially loaded with a call to DosLoadModule, the DLL will be freed 
from this process. If no other processes are currently linked to the DLL, the DLL is re¬ 
leased from memory. If the DLL was initially loaded as a result of load-time dynamic 
linking, the DLL remains linked to the process and is not released from memory. 

Let’s now rewrite APPSAMP to use runtime dynamic linking. We begin by remov¬ 
ing the DLLSAMP library from the link command in our make file. This removes the 
load-time dynamic linking. In our example, we will load the DLL, query the function 
address, and free the DLL every time we want to call into the DLL. Although this will 
cause a lot of loading and unloading, it will demonstrate the procedure for runtime 
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dynamic linking. In practice, you may want to load the DLL when it is first used and not 
release it until the application is terminating. We will call this application APPSAMP2. 
Because we will be retrieving the addresses of the functions using a generic PFN type 
definition, we will need to define atypedeffor each of the functions. This will allow the 
compiler to perform the necessary type checking on the parameters. We add a typedef 
for each exported function to the DLLSAMP.H file. APPSAMP2.C contains the same 
code as APPSAMP.C except that the code for performing runtime dynamic linking has 
been added. 


DLLSAMP.H 


/* 


DLL Sample Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


/* Exported Functions */ 

VOID EXPENTRY CenterWindow (HWND); 

VOID EXPENTRY FillWindow (HWND, HPS, ULONG); 

/* Function typedefs for run-time dynamic linking */ 

#ifndef IBMC 

typedef VOID (APIENTRY *PFNCENTERWINDOW) (HWND); 

typedef VOID (APIENTRY *PFNFILLWINDOW) (HWND, HPS, ULONG); 

#else 

typedef VOID (APIENTRY _PFNCENTERWINDOW) (HWND); 
typedef _PFNCENTERWINDOW *PFNCENTERWINDOW; 
typedef VOID (APIENTRY _PFNFILLWINDOW) (HWND, HPS, ULONG); 
typedef _PFNFILLWINDOW *PFNFILLWINDOW; 

#endif 


*/ 


We also change the make file, resource file, and DEF to reference APPSAMP2 
instead of APPSAMP. The only other changes are to the APPSAMP2 C file. 


APPSAMP2.C 

/* 

APPSAMP2 Program 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 
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#define INCLJDOSMODULEMGR 
#define INCL_WIN 

#include <os2.h> 

#include "appsamp.h" 

#include "dllsamp.h" 

#include "..\..\common\about.h" 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 

VOID CallFillWindow (HWND, HPS); 

VOID CallCenterWindow (HWND); 

HAB hab; 

HWND hWndFrame = 0, 
hWndClient; 

CHAR szTitle[64]; 

ULONG ulColors[3] = { 0X00FF0000, 0X0000FF00, 0X000000FF }; 

ULONG ulCurrentColor = 0L; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU | FCFJ/IENU 

FCF_SIZEBORDER | FCF_MINMAX | FCF_ICON 
FCF_SHELLPOSITION | FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 

} 

VOID CallCenterWindow (HWND hWnd) 

{ 
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CHAR szTitle[40]; 

CHAR szFailBuff [CCHMAXPATH]; 

HMODULE hDLLModule; 

PFNCENTERWINDOW pfnCenterWindow; 

WinQueryWindowText (hWndFrame, sizeof(szTitle), szTitle); 
WinSetWindowText (hWndFrame, "Loading DLL"); 

WinllpdateWindow (hWndFrame); 

if (!DosLoadModule (szFailBuff, sizeof(szFailBuff), "DLLSAMP", 
&hDLLModule)) 

{ 

if (IDosQueryProcAddr (hDLLModule, 0L, "CenterWindow", 
(PFN*)&pfnCenterWindow) || 

IDosQueryProcAddr (hDLLModule, 0L, "CENTERWINDOW", 
(PFN*)&pfnCenterWindow)) 

(*pfnCenterWindow) (hWnd); 

DosFreeModule (hDLLModule); 

} 

WinSetWindowText (hWndFrame, szTitle); 
return; 


VOID CallFillWindow (HWND hWnd, HPS hps) 

{ 

CHAR szTitle[40]; 

CHAR SzFailBuff [CCHMAXPATH]; 

HMODULE hDLLModule; 

PFNFILLWINDOW pfnFillWindow; 

WinQueryWindowText (hWndFrame, sizeof(szTitle), szTitle); 
WinSetWindowText (hWndFrame, "Loading DLL"); 

WinUpdateWindow (hWndFrame); 

if (!DosLoadModule (szFailBuff, sizeof(szFailBuff), "DLLSAMP", 
&hDLLModule)) 

{ 

/* FillWindow is ordinal #2 */ 

if (IDosQueryProcAddr (hDLLModule,2L,NULL,(PFN*)&pfnFillWindow)) 
(*pfnFillWindow) (hWnd, hps, ulColors[ulCurrentColor]); 
DosFreeModule (hDLLModule); 

} 

WinSetWindowText (hWndFrame, szTitle); 
return; 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

HPS hps; 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 
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switch (msg) 

{ 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 
CallFillWindow (hWnd, hps); 

WinEndPaint (hps); 
break; 

case WM_ERASEBACKGROUND: 
mReturn = MRFROMLONG(1L); 
break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_RED: 
case IDM__GREEN: 
case IDM_BLUE: 

ulCurrentColor = L0USH0RT(mp1) - IDM_RED; 
hps = WinGetPS (hWnd); 

CallFillWindow (hWnd, hps); 

WinReleasePS (hps); 
break; 

case IDM_CENTER: 

CallCenterWindow (hWndFrame); 
break; 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


The application window for APPSAMP2 is shown in Figure 10.8. 
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Figure 10.8. 

The primary window for 
the application sample 
using a DLL. 



We have defined two functions to do the necessary work for loading the DLL, re¬ 
trieving the function address, and freeing the DLL. These functions, CallCenterWindow 
and CallFillWindow, start by setting the text in the titlebar window to “Loading DLL.” 
On exit from the function, they reset the title back to its original value. Both functions 
make the same call to DosLoadModule: 

if (!DosLoadModule (szFailBuff, sizeof(szFailBuff), "DLLSAMP", 
&hDLLModule)) 

and DosFreeModule 

DosFreeModule (hDLLModule); 

Because we specify only " DLLSAMP" for the module name, the LIBPATH will be searched. 
The calls to DosQueryProcAddr demonstrate both methods of specifying the function 
to retrieve. CallCenterWindow retrieves the function address by name: 

if (!DosQueryProcAddr (hDLLModule, 0L, "Center_Window", 

(PFN*)&pfnCenterWindow)) 

(*pfnCenterWindow) (hWnd); 

CallFillWindow retrieves the function address by its ordinal: 

/* FillWindow is ordinal #2 */ 

if (!DosQueryProcAddr (hDLLModule, 2L, NULL, (PFN*)&pfnFillWindow)) 
(*pfnFillWindow) (hWnd, hps, ulColors[ulCurrentColor]); 

Two additional functions are used frequently when working with DLLs. 
DosQueryModuleName is used to retrieve the full pathname of a module if you have the 
module handle: 

APIRET APIENTRY DosQueryModuleName(HMODULE hmod, ULONG cbName, PCHAR 
pch); 



Chapter 1U Dynamic Link Libraries 


hmod Module handle of DLL or executable. 

cbName sizeof pch. 

pch Buffer to return full pathname of module. 

With the handle of a module, we can query the full path using: 

CHAR szName[CCHMAXPATH]; 

DosQueryModuleName (hDLLModule, sizeof(szName), szName); 

DosQueryModuleName can also be used for executables. Suppose we know that the 
DLL is located in the same directory as the application, but we can’t be guaranteed the 
directory is in the LIBPATH. We can retrieve the path of the application, remove the 
application’s filename, and append the name of the DLL. We could then pass the com¬ 
plete pathname of the DLL to DosLoadModule: 

PPIB ppib; 

PTIB ptib; 

CHAR szName[CCHMAXPATH]; 

DosGetlnfoBlocks (&ptib, &ppib); 

DosQueryModuleName (ppib->pib_hmte, sizeof(szName), szName); 

DosGetlnfoBlocks will be discussed in detail in Chapter 15, “Miscellaneous Top¬ 
ics.” Suffice it to say that this is how to retrieve the module handle for the current appli¬ 
cation. After this call, szName contains the full path of the application. All that’s left to 
do is to replace the filename with the filename of the DLL. We leave that as an exercise. 

The other function commonly used is DosQueryModuleHandle: 

APIRET APIENTRY DosQueryModuleHandle(PSZ pszModname, PHMODULE phmod); 

pszModname Name of module to locate. Default extension is 

DLL. 

phmod Address of module handle to return. 

DosQueryModuleHandle will return the module handle of the specified module if 
that module is currently loaded in the system. If a full pathname is specified in pszModname, 
it must match exactly the full pathname of the loaded module or else the call will fail. If 
only a filename without an extension is specified, any loaded DLL with that filename 
will be located: 

HMODULE hDLLModule; 

DosQueryModuleHandle ("DLLSAMP", &hDHModule); 

This function is used to determine if a specified module is already loaded in the sys¬ 
tem; however, just because a valid handle may be returned does not mean that your pro¬ 
cess has access to the module. Only if the module has been loaded for your process is the 
handle valid for you to use. 



4§S 



Real-World Programming for 


OS/2 


2.1 


Global versus Instance Data 

So far we have talked only about the fact that code in a DLL is shared among all pro¬ 
cesses linked to the DLL. What about the data in the DLL? How is it shared among the 
processes? Can each process have its own copy of the data? Can we have both shared and 
. nonshared data? All are valid questions, and the answer to each question is YES! We will 
talk about each and show how to define and use each variation of data in a DLL. 

Although OS/2 loads only one copy of the code for a DLL into memory, you have 
control of how the data segment for the DLL is loaded for each instance of the DLL. We 
will refer to an instance of the DLL as a single process’s link to a DLL. An instance of a 
DLL can have both instance and global data. Global, or shared, data is that data shared 
among all instances of a DLL. Instance, or nonshared, data is that data private to an in¬ 
stance of a DLL. Each instance of the DLL has its own copy of instance data. 

When you compile your source files, data is normally placed in the automatic data 
segment. Initialized data is placed in the logical segment _DATA, and uninitialized data is 
placed in the logical segment _BSS or c_common. The name of the automatic data seg¬ 
ment can be renamed using an option switch with most compilers. The code for the sample 
programs demonstrates this. 

Global data is shared among all instances of the DLL. How is this accomplished? Let’s 
start with a diagram of the DLL code and data segment for global data only (see Fig¬ 
ure 10.9). 


Figure 10.9. 

Global data segment 
for a DLL. 


Process 1 Code 



We see that the address for the data reference for both processes (instances) points to 
the same logical address in memory. This logical address maps to the same physical ad¬ 
dress for both processes. The type of data for the default data segment is defined in the 
DEF file with the DATA statement. To define a global, shared data segment, use the SINGLE 
keyword in the DEF file, for example: 
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DATA SINGLE SHARED 

The shareability parameter of the DATA statement defines how all segments other than 
the default data segment are to be allocated. SHARED says all other segments are also glo¬ 
bal, and NONSHARED says all other segments are instance. 

Keep in mind that data in global data segments is not protected from being updated 
by another process while one process is in the middle of using the current value. This is 
due to the preemptive nature of OS/2. One way to protect this type of activity is with 
semaphores. Another is to use instance data for those variables that do not need to be 
shared among processes. 

Instance data is not shared among processes, and each process obtains its own copy 
of the data segment. Look at a diagram for instance data only (see Figure 10.10). 


Figure 10.10. 

Instance data segment 
for a DLL. 


Process 1 Code 


DLL Data - Process 1 



We see in this case that the address for the data reference for both processes points to 
the same logical address. This logical address, however, maps to two different physical 
memory addresses, depending on which process is currently active. How does this hap¬ 
pen when the DLL code contains only one logical address? The key to this is in the use of 
the page table. When a process is executing, its page table is loaded and used for that 
process. When a task switch occurs and another process becomes active, the page table 
for that process is loaded into memory. Because all addresses in the code are logical ad¬ 
dresses, it is possible for the same logical address to map to a different physical address 
(see Figure 10.11). 

The page table entries for two processes are shown. For process 1, logical address 
0x09802000 has not been allocated, whereas for process 2, the same address has been 
allocated and assigned physical address 0x037E5000. Both process 1 and process 2 have 
logical address 0x09804000 allocated, but each points to a different physical address. 
Process 1 maps the logical address to physical address 0x0390F000, whereas process 2 
maps to 0x037E6000. The logical address OxlDCOOOOO is allocated to both processes, 
and it also maps to the same physical address. This is an example of shared data. 
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Figure 10.11. 
Demonstration of how 
the same logical address 
can map to a different 
physical address. 


Process 1 Page Table 


Logical Address 

Physical Address 

0x09802000 

0x09804000 

Not allocated 
0x0390F000 

0x1 DC00000 

0x062E000 

Process 2 Page Table 


Logical Address 

Physical Address 

0x09802000 

0x09804000 

0X037E5000 

0X037E6000 

0x1 DCOOOOO 

0X062E0000 


Physical Memory 


0x00000000 

0x00001000 


- 0X037E5000 
-0X037E6000 


- 0X0390F000 


- 0x062E0000 


We can see that the DLL can refer to the same logical address and that OS/2 will take 
care of switching the page table and mapping the logical address to the correct physical 
address. 

To define an instance, nonshared data segment, use the MULTIPLE keyword on the 
DATA statement in the DEF file. 

DATA MULTIPLE NONSHARED 

A quick look at an example shows the difference between these two methods. The 
same source code is used in both cases, but the DEF file will change to define the data as 
either global or instance. Assume we have a DLL coded with a global variable defined as 
ulCount which is incremented every time that the function IncrementCount is called 
and the new count is returned to the caller: 

/* DLL Code */ 

UL0NG ulCount = 0L; 

UL0NG EXPENTRY IncrementCount () 

{ 

return (++ulCount); 

} 

Assume we have an application that calls the IncrementCount only once and dis¬ 
plays the count in the window. If we start the application twice, causing the DLL to be 
loaded for each process, we see different results for each case. 

For the global data, the DEF file would contain the following DATA statement: 


502 






Chapter JLU Dynamic Link Libraries 


DATA SINGLE SHARED 

The first process would call IncrementCount, and the return value would be 1. The 
second process would call IncrementCount, and the return value would be 2. This as¬ 
sumes the second process is started before the first one terminates. As long as there is a 
process linked to the DLL, the data segment remains loaded. Each successive call to 
IncrementCount, by either process, would continue to increment the same count. 

For the instance data, the DEF file would contain the following DATA statement: 
DATA MULTIPLE NONSHARED 

The first process would call IncrementCount, and the return value would be 1. The 
second process would call IncrementCount, and the return value would again be 1. Each 
successive call to IncrementCount would increment the count maintained for the par¬ 
ticular process making the call. 

It is also possible to have both global and instance data segments for a DLL. This can 
be done in a single source file and with multiple source files. The key to defining both 
global and instance data is that first you must create multiple data segments defining the 
global data in the global data segment and the instance data in the instance data segment. 
Second, you must define the characteristics of these segments in the DEF file. The easi¬ 
est approach is to use multiple source files with one file defining the instance data vari¬ 
ables and to let all other variables be defined as global. Using this approach enables you 
to keep all the instance specific variables together, and you are free to define global vari¬ 
ables in each source file as they are needed. 

To begin, we must create a file to contain our instance-specific data. All variables that 
are to be private to an instance of a DLL are defined in that file. A technique I prefer is to 
define all instance-specific data items as part of a structure called InstanceData. When¬ 
ever an instance variable is being used, it is easily identified by the structure name 
InstanceData. We will use that in our example. We could create a file called DLLINST.H 
to contain the definition of the instance data structure, for example: 

typedef struct tagINSTANCE_STRUCT 

{ 

ULONG ulFlags; 

HAB hab; 

HMQ hmq; 

HWND hWndFrame; 

} INSTANCEDATA_STRUCT; 

The fields here are only arbitrary variables to illustrate our example. Next, we could 
define the file DLLINST.C to actually define the InstanceData structure, for example: 

INSTANCEDATA_STRUCT InstanceData = 

{ 
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0L, 

(HAB)0L, 
(HMQ)0L, 
(HWND)0L 


Our InstanceData is initialized to zeroes, although you could initialize your vari¬ 
ables to any value. The next step is to compile this file and redefine the default data seg¬ 
ment. We give our instance data the name _INSTANCEDATA. All the compilers with which 
the sample code was tested for this book have different methods for defining a name for 
a data segment. Those compilers also differ in how variables are specified and placed into 
each data segment. Examine both the source code and the MAK file for the example 
program for this chapter for the compiler which you use. 

The variable InstanceData is defined to reside in the data segment with name 
_INSTANCEDATA. Anytime an instance data variable is to be used, the InstanceData struc¬ 
ture variable is used: 

InstanceData.ulFlags 
InstanceData.hab 
InstanceData.hmq 
InstanceData.hWndFrame 

Because we have decided that all other data defined in our application is to be global 
data, we do not need to do anything special in defining those variables. They will be placed 
in a data segment other than _INSTANCEDATA. The final step is to define the 
_IN STANCE DATA segment as being nonshared and all others as being shared. The 
application’s DEF file will contain the following statements: 

DATA SINGLE SHARED 

SEGMENTS 

_INSTANCEDATA CLASS 1 FAR_DATA' NONSHARED PRELOAD 

Examine your MAP file to find the exact name and class of the data segment con¬ 
taining your instance data. 

As we saw earlier, the DATA SINGLE SHARED statement defines the automatic data 
segment to be SINGLE (global) and the default for all other segments to be SHARED (glo¬ 
bal). The SEGMENTS statement overrides the attributes for a segment defined. The format 
of the SEGMENTS statement is as follows: 

SEGMENTS 

segment statement 
segment statement 
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Each segment statement defines the attributes for the segment. In general, the seg¬ 
ment statement for DATA segments uses the following format: 

segment-name [CLASS ['classname 1 ]] [segment-attribute] 

segment-name Name of the segment to be defined, 

classname Name of the class for the segment, 

segment-attribute PRELOAD I LOADONCALL 

READONLY I READ WRITE 
IOPL I NOIOPL 

CONFORMING I NONCONFORMING 
SHARED I NONSKARED 

Because we want the_INSTANCEDATA segment to be nonshared, we use the NONSHARED 
segment attribute. 

Initialization and Termination 

An important aspect of proper DLL maintenance is keeping track of the processes that 
are currently using the DLL. One way of doing this is to define a function in the DLL 
that is called by a process when the process starts and another function in the DLL that 
is called when it terminates. This relies on the application to behave properly and to make 
the calls at the current time. An alternative, and a more practical method, is for the DLL 
to keep track of this activity. This is accomplished by using an Initialization/ 
Termination function. It is called an Initialization/Termination function because 
OS/2 calls the function when the DLL is loaded for a process and when it is unloaded for 
a process. 

The use of an initialization and termination function allows the DLL to perform any 
process-specific initialization and upon termination to clean up data or structures that 
were allocated. The initialization function for OS/2 DLLs has the following prototype: 

ULONG _stdcall DLL_InitTerm (HMODULE hModule, ULONG ulTerminating); 

hModule Module handle of the DLL. 

ulTerminating Initialization/Termination flag. 

0x00 DLL is initializing. 

0x01 DLL is terminating. 


Notes __stdcall in the preceding definition is changed to _System for the IBM 
C/Set compiler. 
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The return code indicates the success or failure of the DLL initialization code to 
OS/2. Return FALSE if the initialization is unsuccessful. OS/2 will then unload the DLL. 
If the DLL is being loaded as part of load-time dynamic linking, the application will fail 
to start. Return TRUE if the initialization is successful. The DLL will remain in memory 
until unloaded. 

The same function is called when the DLL is being loaded and when it is being un¬ 
loaded. The ulTerminating flag indicates that is occurring. If you are using the IBM 
C/Set compiler, this function will be called at initialization and termination. However, 
for the other compilers, defining this function alone does not define the function to be 
called at initialization and termination. This entry point is defined within an assembly 
language source file. The simplest assembly file to use is the following one. 

DLLINIT.ASM 

. 386p 

INIT SEGMENT BYTE PUBLIC 'CODE 1 

EXTRN _DLL_InitTerm:near 

assume CS:FLAT, DS:FLAT, ES:FLAT, SS:FLAT 

INIT ENDS 

END _DLL_InitTerm 

When this file is assembled and linked with the DLL, the function DLL_I nit Term is 
defined as the DLL entry point. The only remaining thing to specify for our Initial¬ 
ization/Termination function is when it should be called. This is defined in the DEF 
file in the LIBRARY statement. To have this function called only once when the first pro¬ 
cess loads the DLL, use the INITGLOBAL parameter, which is the default in the DEF file: 

LIBRARY DLLSAMP INITGLOBAL 

To have this function called for every process that loads the DLL, use the 
INITINSTANCE parameter, as in this sample statement: 

LIBRARY DLLSAMP INITINSTANCE 

If you need to perform both instance and global initialization, do this by defining 
a flag that is initialized to TRUE and set to FALSE after the first instance initializes. There¬ 
after, the global initialization is not performed because this flag is cleared: 

BOOL bFirstlnstance = TRUE; 

ULONG _stdcall DLL_InitTerm (HMODULE hModule, ULONG ulTerminating) 

{ 



if (bFirstlnstance) 
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{ 

perform global initialization 
bFirstlnstance = FALSE; 

} 

perform instance initialization 

} 

Examples of global initialization may include allocating shared memory to be sub¬ 
allocated by the DLL, incrementing a count of processes linked to the DLL, or creating 
semaphores. Examples of instance initialization may include recording the process iden¬ 
tifier, loading instance-specific resources, or gaining access to shared memory or sema¬ 
phores. 

Another point that we have not discussed so far is the use of the C runtime library 
functions. When C runtime library functions are used for an application, a call to the C 
runtime library initialization function is inserted into the start-up code. This is not done 
for DLLs when you define an alternate entry point as we just did. Because a DLL can 
have only one entry point, it may be necessary for you to explicitly call the C runtime 
library initialization function as part of your instance initialization. The name of the C 
runtime library initialization function will vary depending on the compiler you are 
using. Refer to your documentation to see if you are required to use certain C runtime 
library functions. 

DosExitList 

If you have created DLLs prior to OS/2 2.1, you are probably familiar with an exit list 
handler. An ex it list handler is installed during initialization of a DLL and defines a 
function that is to be called when the current process terminates. With OS/2 now auto¬ 
matically calling the Initialization /Termination function, when the process termi¬ 
nates, it may no longer be necessary for you to install an exitlist handler. There are 
two circumstances when you may still want to have an exitlist handler even with an 
Initialization/Termination function. 

The first circumstance is when the termination of your process requires you to clean 
up window or graphics objects. An example would be when your DLL creates a DC that 
is left open when the process terminates, which then requires the termination code to 
close and delete this DC. This requirement is due to the current sequence in which a 
process is cleaned up. When a process terminates the order of events is as follows: 

1. Call all exitlist handlers by using the invocation order. 

Call the Initialization/Termination functions of all 32-bit DLLs. 
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Because PMWIN and PMGPI install exitlist handlers for each process, their 
exitlist handler will be called before the 32-bit DLL termination function. Part of 
PMWIN and PMGPI cleanup involves destroying remaining windows and freeing 
bitmaps and other allocated graphics objects. An open DC, however, is not properly 
cleaned up by the system. By the time the 32-bit DLL termination code is called, both 
PMWIN and PMGPI have cleaned up, and calls into either DLL most likely will result 
in a failed function call. This particular sequence effectively eliminates the capability of 
the termination code to call into PMWIN or PMGPI to perform any cleanup. Installing 
an exitlist handler, thus, would be appropriate if you need to make calls into either 
DLL during termination. 

The second circumstance is a more specialized reason, but nonetheless useful tactic. 
If you don’t want your DLL to be unloaded by OS/2 when DosFreeModule is called, 
you can install an exitlist handler. By installing an exitlist handler, you are effec¬ 
tively establishing a dependency with the OS/2 loader that the DLL cannot be unloaded 
until the process terminates. The reason is obvious. If you install an exitlist handler 
and have a call DosFreeModule actually free the DLL from memory, when the process 
terminates, the code will no longer be in memory, and the termination sequence will trap. 
After an exitlist handler is installed for a process, this dependency is established and is 
not removed, even if the exitlist handler is removed. 

An exitlist handler is installed or removed by using the DosExitList function: 
APIRET APIENTRY DosExitList(ULONG ordercode, PFNEXITLIST pfn); 

ordercode The low byte of the low word indicates 

the exitlist function: 

EXLST_ADD (1) Add the function to the exitlist. 

EXLSTJRJEMOVE (2) Remove the function from the 
exitlist. 

EXLST_EXIT (3) Transfer to the next function in the 

termination sequence.The high byte of 
the low word indicates the order in 
which the exitlist should be called. 

The exitlist functions are called in 
order based on their invocation order 
from lowest(0) to highest (233). 

pfn Function address to install.8 

To install the function DLL_ExitList as an exitlist handler: 

DosExitList (EXLST_ADD J 0x00007000, (PFNEXITLIST)DLL_ExitList); 
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The invocation order specified here is 112 (0x70). To remove an exit list handler: 

DosExitList (EXLST_REM0VE, (PFNEXITLIST)DLL_ExitList); 

When the exit list function has been called and it is through performing its func¬ 
tion, it MUST tell OS/2 to continue with the next exitlist handler in the sequence. 
The last statement in the exitlist code must be as follows: 

DosExitList (EXLST_EXIT, (PFNEXITLIST)DLL_ExitList); 

Multiple exitlist handlers can be installed for the same process. The format of the 
exitlist function is as follows: 


VOID EXPENTRY DLL_ExitList (ULONG ulCode); 


ulCode 


TCJEXIT 

TC_HARDERROR 

TC_TRAP 

TC_KILLPROCESS 
T C_EXCEPTION 


Code indicating reason for exitlist 
being called: 

(0) Terminating normally. 

(1) Hard-error encountered. 

(2) Trap operation (16-bit child 
process). 

(3) DosKillProcess. 

(4) Exception operation (32-bit 
child process). 


OS2.INI 

Two entries are in the OS2.INI file which specify that certain DLLs be loaded at particu¬ 
lar times. These entries should not be used indiscriminately to force your DLL to be 
preloaded, as that can affect system performance and memory usage. Both entries are under 
the application name “SYS_DLLS.” 

Application Key Description 

SYS_DLLS LoadOneTime Load the DLLs listed when the 

system is booted. 

SYS_DLLS LoadPerProcess Load the DLLs listed for every 

process that is started. 

The format of the data for each of these entries is a list of DLLs separated by a space 
and finally terminated with a NULL byte. When these DLLs are loaded, OS/2 will auto¬ 
matically call the function with ordinal 1. If you decide you need to use this capability, 
ensure that you have a function with ordinal 1 defined which either performs some set¬ 
up on the first load or is just a stub function. No parameters are passed to this function. 
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There is an obvious downfall of this. If you install a DLL this way and the DLL causes 
a trap or hangs, it becomes difficult to reboot your system because this DLL will be au¬ 
tomatically loaded each time. Use this capability with caution —caveat emptorl 

Resource-Only DLLs 

You can also use DLLs to define resources to be loaded by multiple processes. Although 
you cannot directly share most resources among processes, you can use the resources of a 
DLL for your process. The resources for the DLL are bound into the DLL just as they are 
for an application—using the resource compiler. When you want to load a resource from 
a DLL, specify the module handle for the DLL rather than NULL (indicating the re¬ 
sources are in the executable). 

Perhaps you have some bitmaps created for various screen resolutions. Because you 
probably don’t want to bind every version of the bitmap into your executable, you can 
create resolution-specific DLLs, each containing the bitmaps and so on, required for that 
resolution. When your application is initializing, it can detect the screen resolution and 
perform runtime dynamic linking to load the appropriate resource DLL. The applica¬ 
tion can then load the resources using the module handle of the DLL and use the same 
resource identifier regardless of which DLL was loaded. 

Thermometer Application 

Our sample application will use extensively all the capabilities of DLLs as well as code 
from our earlier chapters on drawing and memory. We will create two general purpose 
DLLs, and our application will use them to assist in the display and operation of a basic 
dialog box. Both DLLs will use instance initialization, although only one will have both 
global and instance data. 

The first DLL, CONTROLS.DLL, is a general purpose DLL demonstrating how 
you can define and create your custom window classes in a DLL. Having the classes de¬ 
fined in a DLL enables you to use those same window classes in many applications. The 
BEVEL control is a window that draws one of various forms of sculptured bevels. For 
example, we could have various bevel windows as shown in Figure 10.12. 

The THERMOMETER control is a window that displays data shown as percent¬ 
ages on a thermometer. We will draw our thermometer using code we created earlier in 
the book. An example of our thermometer control showing a percentage of data is shown 
in Figure 10.13. 
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Figure 10.13. 
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To allow any application using this DLL to use these window classes, we must regis¬ 
ter these two classes for each application. This will be handled through the use of in¬ 
stance initialization. 

The second DLL, MEMDLL.DLL, is a general purpose DLL demonstrating how 
you can perform memory suballocation for both private and shared data. This DLL shows 
the usage of both instance and global data. In addition to providing memory suballocation 
for both private and shared data, it also performs memory cleanup when the application 
terminates. 

Each application will have its own private memory suballocation object, and each 
will share a shared memory suballocation object. This DLL will also use instance initial¬ 
ization to create the private memory suballocation object and to gain access to the shared 
memory suballocation object. The shared memory suballocation object will be maintained 
in global data, and the private memory suballocation object will be maintained in in¬ 
stance data. 
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Let’s take a detailed look at each DLL. We start with the CONTROLS.DLL. The 
first thing to define is the external interface for our two controls. This includes the names 
of the control class, the styles and messages for each control, and any additional func¬ 
tions to be exported. These are defined in CONTROLS.H. 


CONTROLS.H 

/* 

Controls Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

. */ 


GENERAL USE FUNCTIONS 


VOID EXPENTRY CenterWindow (HWND); 


BEVEL CONTROL 


#define BEVELCLASS "BEVEL" 


/* Use low word of style for private style flags */ 


#define BVS_BEVELIN 
#define BVS_BEVELOUT 
#define BVS_RECTANGLE 
#define BVS_LINE 
#define BVS_FILL 
#define BVS_PREVID 
#define BVS_PREVWINDOW 


0x00000000 
0x00000001 
0x00000000 
0x00000002 
0X00000004 
0x00000008 
0X00000010 


#define BVS IDMASK 0x00008000 


/* Bevel control messages */ 

#define BVM_SETC0L0R WM_USER+1 
#define BVM_SETTHICKNESS WMJJSER+2 
#define BVM RESIZE WM_USER+3 


THERMOMETER CONTROL 


#define THERMOMETERCLASS "THERMOMETER 
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/* Use low word of style for private style flags */ 
#define THSJMOPERCENT 0x00000001 


/* Thermometer control 
#define THM_SETRANGE 
#define THM_SETVALUE 
#define THM SETCOLOR 


messages */ 
WMJJSER+1 
WM_USER+2 
WM USER+3 


This DLL also contains the CenterWindow function from our earlier example. The 
bevel control’s class name is BEVELCLASS. Any application can use this identifier to cre¬ 
ate a window of this class. Our bevel contains seven styles: 


Style 

BVS_BEVELIN 

BVS_BEVELOUT 

BVS_RECTAJNGLE 

BVSJLINE 

BVSJFILL 

BVS_PREVID 


BVS_PREVWINDOW 


Description 

Draw in a depressed state (default). 
Draw in a raised state. 

Control is a rectangle (default). 

Control is a line. 

Fill the control. 

Union the size and location of the 
previous sibling windows until the 
window with the specified ID 
is found, and size the control to 
enclose all of them. 

Use previous sibling window to size the 
control. 


BVS_IDMASK is not really a style, but a mask used in defining the identifier of the 
bevel when the BVS_PREVID style is used. Both the BVS_PREVID and BVS_PREVWINDOW 
styles are an easy way for you to allow the bevel to size itself to enclose a defined set of 
sibling windows. The BVS_PREVWINDOW style causes the bevel to get the size and location 
of the previous sibling window (in Z-order) and to size itself to enclose that window. 
The BSV_PREVID style causes the bevel to get the size and location of all previous sibling 
windows (in Z-order) until the sibling window with the specified ID is found and then 
to size itself to enclose those windows. The identifier of the bevel is specified as follows: 

sibling-window-identifier ] BVS_IDMASK 

When either BVS_PREVWINDOW or BVS_PREVID is specified, the x, y, and cx fields of 
the window have special meaning. The x and y fields specify the thickness of the bevel in 
the horizontal and vertical directions. The cx field specifies the gap between the previous 
sibling window(s) and the bevel. For example, to create a bevel with a thickness of 2 pix¬ 
els in both directions and a gap of 4 pixels between the previous sibling window and the 
bevel, the following call would be made: 
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WinCreateWindow (HWND_DESKTOP, BEVELCLASS, M11 , 

BVS_RECTANGLE | BVS_BEVELIN | BVS_PREVWINDOW, 

2L, 2L, 4L, 0L, hWndOwner, HWNDJTOP, -1, NULL, NULL); 

We can use the same example to create a bevel, enclosing all the previous sibling 
windows until a window with ID 100 is found: 

WinCreateWindow (HWND_DESKTOP, BEVELCLASS, "", 

BVS_PREVID, 2L, 2L, 4L, 0L, hWndOwner, HWND_T0P, 

100 | BVS_IDMASK, NULL, NULL); 

Two messages are recognized by the bevel control. BVM_SETC0L0R is used to change 
the border and interior color for a control window: 

BVM_SETC0L0R 

mpl = MAKELONG (bordercolorindex, interiorcolorindex) 
mp2 = not used 

Both the bordercolorindex and interiorcolorindex are system-defined identi¬ 
fiers. The default value is MAKELONG (SYSCLR_BUTTONDARK, SYSCLR_BUTTONMIDDLE). 
To change the fill color to red, use the following: 

WinSendMsg (hWndBevelControl, BVM_SETC0L0R, 

MAKELONG (SYSCLR_BUTTONDARK, CLR_RED), 0L); 

BVM_SETTHICKNESS is used to change the thickness of the bevel’s edges: 

BVM_SETTHICKNESS 

mpl = MPFROMSHORT (bevelthickness) 
mp2 = not used 

The default thickness is 1. To change the thickness to 4, use the following: 

WinSendMsg (hWndBevelControl, BVM_SETTHICKNESS, MPFROMSHORT(4), 0L); 

The thermometer control’s class name is THERMOMETERCLASS. An application can use 
this identifier to create a window of this class. Our thermometer always displays the 
thermometer’s temperature as a percentage of a value within the specified range. We need 
a mechanism for defining this range and setting the current value. 

Our thermometer contains no additional styles but does define three messages. 
THM_SETRANGE sets the range of values: 

THM_SETRANGE 

mp 1 = Low value of range. 
mp2 = High value of range. 

To set our range from 0 to 500, use the following: 

WinSendMsg (hWndThermoCtl, THM_SETRANGE, 0L, 500L); 
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THM_SETVALUE is used to set the current value of the thermometer. When the ther¬ 
mometer gets this message, it redraws the interior of the thermometer to reflect the new 
value: 

THM_SETVALUE 

mp 1 = Current value. 
mp2 = Not used. 

To set the current value to 312, use the following: 

WinSendMsg (hWndThermoCtl, THM_SETVALUE, 312L, 0L); 

THM_SETC0L0R is used to change the color the thermometer window is filled with 
and its background (unfilled) color: 

THM_SETC0L0R 

mpl = MAKELONG(fillcolorindex, backgroundcolorindex). 
mp2 = Not used. 

The default value is red with a pale gray background. To change the color to blue 
with a pale gray background, use the following: 

WinSendMsg (hWndThermoCtl, THM_SETC0L0R, 

MAKELONG (CLR_BLUE, CLR_PALEGRAY), 0L); 

With the definition of our controls, we move to defining the definition (DEF) file 
for the CONTROLS.DLL. 

CONTROLS.DEF 

LIBRARY CONTROLS INITINSTANCE 

DESCRIPTION 'Controls DLL 1993 Blain, Delimon, & English' 

PROTMODE 

CODE MOVEABLE 

DATA MOVEABLE SINGLE 

EXPORTS 

CenterWindow @1 

BevelWndProc @2 

ThermometerWndProc @3 

The library is defined and named in our first line: 

LIBRARY CONTROLS INITINSTANCE 
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The library name is CONTROLS, and we want our initialization code to be called for 
each instance of the DLL. Because we don’t have a need for instance data, we define the 
data segment to be global data: 

DATA MOVEABLE SINGLE 

CenterWindow is exported for use by other applications. 

We have defined our DLL to be INITINSTANCE and, therefore, must define an ini¬ 
tialization function. Our initialization function is defined in the CTLINIT.ASM file. 


CTLINIT.ASM 

; Controls DLL Initialization 

; Define the initialization/termination entry point for the 
; Controls DLL 

. 386p 

ifdef_TASM_ 

model flat,pascal 
endif 

_TEXT SEGMENT DWORD USE32 PUBLIC 'CODE' 

EXTRN _InitializeControlDll:near 

ifdef_MASM386_ 

ASSUME CS: FLAT, DS: FLAT, ES: FLAT 
endif 

_DLLEntry: 

jmp __InitializeControlDll 

_TEXT ENDS 

END _DLLEntry 


This basic assembler file defines our initialization function as 
“initializeControlDLL.” This function will be called both when the DLL is loaded 
and when unloaded for each instance of the DLL. 

Let’s now take a look at our implementation of these controls. 
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CONTROLS.C 

/* . 

Controls DLL 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 

/* Bevel Control 

Class Name - BEVELCLASS 
Styles 

BVS_BEVELIN - Draw bevel inwards 

BVSJ3EVEL0UT - Draw bevel outwards 

BVS_RECTANGLE - Draw a beveled rectangle 

BVS_LINE - Draw a beveled trough or fence 

BVS_FILL - Fill interior 

BVS_PREVID - Size bevel to encompass all previous sibling 

windows until window with specified ID is 
reached. The windows ID is specified as the ID 
of the window to stop at; or'd with BVS_IDMASK 
x Position is horizontal gap between bevel and 
windows 

y Position is vertical gap between bevel and 
windows 

cx is border width (0 is nominal width border) 
BVS_PREVWINDOW - Size bevel to encompass previous sibling window 
x Position is horizontal gap between bevel 
and windows 

y Position is vertical gap between bevel 
and windows 

cx is border width (0 is nominal width border) 

Messages 

BVM_SETC0L0R - mpl MAKELONG(bordercolorindex, 

interiorcolorindex) 

mp2 0L 

BVM_SETTHICKNESS - mpl MPFROMSHORT (bevelthickness) 

BVM_RESIZE - mpl MAKELONG(horizontalgap, verticalgap) 


Thermometer control 

Class Name - THERMOMETER CLASS 
Messages 

THM_SETRANGE - mpl Low value of range 
mp2 High value of range 
THM_SETVALUE - mpl Current value 

THM_SETC0L0R - mpl MAKELONG(fillcolorindex, 

backgroundcolorindex) 


*/ 
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#define INCL_DOS 

#define INCL_DOSERRORS 

#define INCL_WIN 

#define INCL GPIPRIMITIVES 


#include <os2.h> 
#include "controls.h 


/* Window functions */ 

MRESULT EXPENTRY BevelWndProc (HWND , ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY ThermometerWndProc (HWND,ULONG,MPARAM,MPARAM); 

/* Undocumented WinDrawBorder flags */ 


#define DB_RAISED 0x0400 
#define DB_DEPRESSED 0x0800 
#define DB_TROUGH 0x1000 
#define DB__FENCE 0x2000 
#define DB FIELD 0x4000 


#define DB CORNERBORDER 0x8000 


/* Shared data placed into initialized variables data segment */ 
HMODULE hModDll = 0; 


/* Bevel window extra bytes */ 


#define QWL_COLORS 
#define QWS_THICKNESS 
#define BEVELEXTRA 


0 

QWL_C0L0RS + sizeof(ULONG) 
QWS_THICKNESS + sizeof(USHORT) 


/* Thermometer window extra bytes */ 


#define QWL_LOWERRANGE 
#define QWL_UPPERRANGE 
#define QWL_VALUE 
#define QWL_COLOR 
#define THERMOMETEREXTRA 


0 

QWL_LOWE R RAN G E + 
QWLJJPPERRANGE + 
QWL_VALUE + 
QWL COLOR + 


sizeof(ULONG) 
sizeof(ULONG) 
sizeof(ULONG) 
sizeof(ULONG) 


#ifdef _IBMC_ 

ULONG _System _DLL_InitTerm (HMODULE hModule, 

ULONG ulTerminating) 

#else 

ULONG _stdcall InitializeControlDll (HMODULE hModule, 

ULONG ulTerminating) 

#endif 

{ 


BOOL bResult; 
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if (ulTerminating & 0x01) 
return (FALSE); 
else 
{ 

/* Register the window control classes */ 
bResult = 

WinRegisterClass ( 

(HAB)0, BEVELCLASS, BevelWndProc, 

CS_HITTEST | CS_SIZEREDRAW, BEVELEXTRA) && 
WinRegisterClass ( 

(HAB)0, THERMOMETERCLASS, ThermometerWndProc, 
CS_SIZEREDRAW, THERMOMETEREXTRA); 

} 

/* Save the module handle when we get loaded. The module handle 
will be the same for all instances of the DLL */ 

hModDll = hModule; 

return ((ULONG)bResult); 

} 


VOID EXPENTRY CenterWindow (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd, &Rectl); 

WinSetWindowPos (hWnd, HWND_T0P, (ulScrWidth-Rectl.xRight)/2, 
(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_MOVE | SWP_ACTIVATE); 
return; 


VOID QueryBorderRect (HWND hWnd, ULONG ulStyle, PRECTL pRectl) 

{ 

HWND hWndPrev; 

SWP Swp; 

USHORT usID; 

RECTL RectlPrev; 


/* If style is BVS_PREVID, then size the bevel to encompass 
all previous sibling windows until a window with the 
specifed ID is located. 

If style is BVS_PREVWINDOW, then size the bevel to encompass 
the previous sibling window. */ 
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WinSetRect ((HAB)0L, pRectl, 0L, 0L, 0L, 0L); 

if (ulStyle & BVS_PREVWINDOW) 

{ 

if ((hWndPrev = WinQueryWindow (hWnd, QW_PREV)) != 0) 

{ 

WinQueryWindowPos (hWndPrev, &Swp); 

WinSetRect ((HAB)0L, pRectl, Swp.x, Swp.y, 

Swp.x+Swp.cx, Swp.y+Swp.cy); 

} 

} 

else 

{ 

hWndPrev = hWnd; 

usID = WinQueryWindowUShort (hWnd, QWS_ID); 

usID &= ~BVS_IDMASK; 

/* Union the bounding rectangle of all sibling windows 

until window with ID usID is reached */ 

while ((hWndPrev = WinQueryWindow (hWndPrev, QW_PREV)) != 0) 

{ 

WinQueryWindowPos (hWndPrev, &Swp); 

WinSetRect ((HAB)0L, &RectlPrev, Swp.x, Swp.y, Swp.x+Swp.cx, 
Swp.y+Swp.cy); 

WinUnionRect ((HAB)0L, pRectl, pRectl, &RectlPrev); 
if (WinQueryWindowUShort (hWndPrev, QWS_ID) == usID) 
break; 

} 

} 

return; 


MRESULT EXPENTRY BevelWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

RECTL Recti; 

HPS hps; 

ULONG ulStyle; 

ULONG ulDrawStyle; 

ULONG ulColors; 

ULONG ulThickness; 

switch (msg) 

{ 

case WM_CREATE: 

/* Initialize border and interior colors */ 
WinSetWindowULong (hWnd, QWL_COLORS, 

MAKELONG (SYSCLR_BUTTONDARK, SYSCLR_BUTTONMIDDLE)); 
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ulStyle = WinQueryWindowllLong (hWnd, QWL_STYLE); 
if (ulStyle & (BVS_PREVID ] BVS_PREVWINDOW)) 

{ 

SWP SwpBevel; 

/* Query bevel window parameters 

x Position specifies the horizontal gap between 
bevel and sibling windows 
y Position specifies the vertical gap between 
bevel and sibling windows 
cx specifies the width of the bevel */ 

WinQueryWindowPos (hWnd, &SwpBevel); 

QueryBorderRect (hWnd, ulStyle, &Rectl); 

/* Position the bevel window */ 

WinSetWindowPos (hWnd, 0, 

Recti.xLeft - SwpBevel.x, 

Recti.yBottom - SwpBevel.y, 

Recti.xRight - Recti.xLeft + (SwpBevel.x « 1), 

Recti.yTop - Recti.yBottom + (SwpBevel.y « 1), 

SWP_MOVE | SWP_SIZE); 

/* If width is zero use nominal width bevel */ 
if (SwpBevel.cx == 0) 

SwpBevel.cx = 1; 

WinSetWindowUShort (hWnd, QWS_THICKNESS, (USHORT)SwpBevel.cx); 

} 

else 

WinSetWindowUShort (hWnd, QWS_THICKNESS, 1); 
break; 

case BVM_RESIZE: 

ulStyle = WinQueryWindowULong (hWnd, QWL_STYLE); 
if (ulStyle & (BVS_PREVID | BVS_PREVWINDOW)) 

{ 

RECTL Recti; 

QueryBorderRect (hWnd, ulStyle, &Rectl); 

/* Position the bevel window */ 

WinSetWindowPos (hWnd, 0, 

Recti.xLeft - SHORT1FROMMP(mp1), 

Recti.yBottom - SH0RT2FR0MMP(mp1), 

Recti.xRight - Recti.xLeft + (SHORT1FROMMP(mpl) « 1), 
Recti.yTop - Recti.yBottom + (SH0RT2FR0MMP(mp1) « 1), 
SWP_M0VE | SWP_SIZE); 

} 

break; 
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case BVM_SETCOLOR: 

/* LOUSHORT(mpl) == Border color 

HIUSHORT(mpl) == Interior color */ 

WinSetWindowULong (hWnd, QWL_C0L0RS, (ULONG)mpl); 

/* Repaint bevel with new color */ 

WinlnvalidateRect (hWnd, NULL, FALSE); 
break; 

case BVM_SETTHICKNESS: 

WinSetWindowUShort (hWnd, QWS_THICKNESS, SH0RT1FROMMP(mpl)); 
break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

ulColors = WinQueryWindowULong (hWnd, QWL_C0L0RS); 
ulThickness = (ULONG)WinQueryWindowUShort (hWnd, QWS_THICKNESS) 
ulStyle = WinQueryWindowULong (hWnd,QWL_STYLE) & 0X0000FFFF 

ulDrawStyle = 0L; 
if (ulStyle & BVS_BEVELOUT) 
if (ulStyle & BVS_LINE) 
ulDrawStyle |= DB_FENCE; 
else 

ulDrawStyle |= DB_RAISED; 
else if (ulStyle & BVS_LINE) 
ulDrawStyle j= DB_TROUGH; 
else 

ulDrawStyle j= DB_DEPRESSED; 
if (ulStyle & BVS_FILL) 

ulDrawStyle |= DB_INTERIOR; 

WinQueryWindowRect (hWnd, &Rectl); 

WinDrawBorder (hps, &Rectl, ulThickness, ulThickness, 

LOUSHORT(ulColors), HIUSHORT(ulColors), ulDrawStyle); 

WinEndPaint (hps); 
mReturn = 0L; 
break; 

case WMJHITTEST: 

/* Allow mouse message to pass through this window */ 

mReturn = (MRESULT)HT_TRANSPARENT; 

break; 


default: 

bHandled = FALSE; 
break; 
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if (IbHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 


return (mReturn); 

} 


ULONG CalculatePercentage (HWND hWnd) 

{ 

LONG HowerRange; 

LONG lUpperRange; 

LONG lValue; 


} 


lLowerRange = WinQueryWindowULong (hWnd, QWL_LOWERRANGE); 

lUpperRange = WinQueryWindowULong (hWnd, QWLJJPPERRANGE); 

lValue = WinQueryWindowULong (hWnd, QWL_VALUE); 

if (lUpperRange <= lLowerRange) 
return (1L); 
else 

return ( ((lValue - lLowerRange) * 100) / 

(lUpperRange - lLowerRange) ); 


VOID DrawPercentages (HPS hps, PRECTL pRectl) 

{ 

ULONG ulTop; 

ULONG ulBottom; 

POINTL Ptl; 

RECTL Recti; 

ULONG ulHeight; 


Recti.xLeft = pRectl->xRight *6/10; 

Recti.xRight = pRectl->xRight *3/4-2; 

Ptl.x = pRectl->xRight *3/4; 

ulTop = pRectl->yTop *95 / 100; 

ulBottom = pRectl->yTop / 4; 

ulHeight = ulTop - ulBottom; 

Recti.yBottom = ulTop; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_FENCE); 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 4, "100%"); 

Recti.yBottom = ulBottom + (ulHeight * 9) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_TROUGH) 


Recti.yBottom = ulBottom + (ulHeight * 8) / 10; 
Recti.yTop = Recti.yBottom + 2; 
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WinDrawBorder (hps, &Rectl, 1L, 1L, CLRJ3LACK, CLR_WHITE,DB_FENCE); 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 3, "80%"); 

Recti.yBottom = ulBottom + (ulHeight * 7) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_TROUGH); 

Recti.yBottom = ulBottom + (ulHeight * 6) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_FENCE); 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 3, "60%"); 

Recti.yBottom = ulBottom + (ulHeight * 5) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_TROUGH); 

Recti.yBottom = ulBottom + (ulHeight * 4) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_FENCE); 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 3, "40%"); 

Recti.yBottom = ulBottom + (ulHeight * 3) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLRJVHITE,DB_TROUGH); 

Recti.yBottom = ulBottom + (ulHeight * 2) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR__BLACK, CLR_WHITE,DB_FENCE) ; 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 3, "20%"); 

Recti.yBottom = ulBottom + (ulHeight * 1) / 10; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLR_BLACK, CLR_WHITE,DB_TROUGH); 

Recti.yBottom = ulBottom; 

Recti.yTop = Recti.yBottom + 2; 

WinDrawBorder (hps, &Rectl, 1L, 1L, CLRJ3LACK, CLR_WHITE,DB_FENCE); 
Ptl.y = Recti.yBottom - 2; 

GpiCharStringAt (hps, &Ptl, 2, "0%"); 

return; 

> 

BOOL APIENTRY DrawTemperature (HPS hPS, PRECTL pRectl, LONG IColor, 

LONG IBackColor, LONG IPercent) 
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/* 


*\ 


This function will fill draw the vertical bar portion of the 
thermometer. IColor is used to fill IPercent of the bar starting 
at the top of the bulb. IBackColor is used to fill the remainder 
of the bar. The rectangle identified by pRectl should be identical 
to that supplied to DrawThermometer. 

hPS Presentation space to render in. 

pRectl Bounding box of the thermometer. 

IColor Color index used to fill bulb and stem of thermometer. 
IBackColor Color to fill the remainder of the stem (100 - IPercent). 
IPercent Amount to fill the thermometer. Valid range is 0 to 100. 


\*.*/ 

{ 

AREABUNDLE ab; 

RECTL Recti; 

int iWidth = (pRectl->xRight - pRectl->xLeft) / 3; 

int iBoxHeight = pRectl->yTop - pRectl->yBottom; 

int iBarHeight = (iBoxHeight * 70) / 100; 

/* Range check the percent */ 
if (IPercent > 100) 

IPercent = 100; 
else if (IPercent < 0) 

IPercent = 0; 

Recti.xLeft = pRectl->xLeft + iWidth; 

Recti.yTop = pRectl->yTop - (iBoxHeight * 5) / 100; 
if (IPercent) 

Recti.yBottom = Recti.yTop - 

((iBarHeight * (100 - IPercent)) / 100); 

else 

Recti.yBottom = Recti.yTop - iBarHeight; 

Recti.xRight = pRectl->xRight - iWidth; 

ab.IColor = IBackColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_COLOR,0,(PBUNDLE)&ab); 

GpiMove (hPS,(PPOINTL)&Rectl); 

GpiBox (hPS,DR0_FILL,(PPOINTL)&Rectl.xRight,0,0) ; 

Recti.yTop = Recti.yBottom - 1; 

Recti.yBottom = pRectl->yBottom + (iBoxHeight * 20) / 100; 
ab.IColor = IColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_C0L0R,0,(PBUNDLE)&ab); 

GpiMove (hPS,(PPOINTL)&Rectl); 

GpiBox (hPSjDRO_FILL,(PPOINTL)&Rectl.xRight,0,0); 
return (TRUE); 
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BOOL APIENTRY DrawThermometer (HPS hPS, PRECTL pRectl, LONG IStyle, 

LONG IColor, LONG IBackColor, LONG IPercent) 
/*.*\ 


This function will draw the outine of a thermometer scaled to 
the supplied rectangle in the give presentation space. The bulb 
of the rectangle is filled with IColor and the remainder is drawn 
by the DrawTemperature function. 


hPS Presentation space to render in. 

pRectl Bounding box of the thermometer 

IStyle Currently undefined. 

IColor Color index used to fill bulb and stem of thermometer. 
IBackColor Color to fill the remainder of the stem (100 - IPercent). 
IPercent Amount to fill the thermometer. Valid range is 0 to 100. 


\*. 

{ 

LINEBUNDLE 

AREABUNDLE 

ARCPARAMS 

POINTL 

POINTL 

POINTL 

POINTL 

FIXED 

RECTL 

int 


lb; 

ab; 

arcparms; 

lPtCenter; 

IStartPt; 
lEndPt; 
lPt; 

fxStartAngle,fxSweepAngle; 
BulbRectl; 

iBoxHeight = pRectl->yTop 


pRectl->yBottom; 


*/ 


/* Calculate the height of the bulb to be 25% of the total height */ 
BulbRectl = *pRectl; 

BulbRectl.yTop = BulbRectl.yBottom + (iBoxHeight * 25) / 100; 


/* define the bounding box for the arc */ 

arcparms.lP = (BulbRectl.xRight - BulbRectl.xLeft) / 2L; 

arcparms.lQ = (BulbRectl.yTop - BulbRectl.yBottom) / 2L; 

arcparms.lR = 0L; 

arcparms.lS = 0L; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 


/* Calculate the center point of bulb */ 
lPtCenter.x = BulbRectl.xLeft + arcparms.lP; 
lPtCenter.y = BulbRectl.yBottom + arcparms.lQ + 1; 

/*.-.*\ 

Draw the bulb 

\*.*/ 

/* Draw an invisble arc from current location to start angle */ 
fxStartAngle = MAKEFIXED(120,0); 
fxSweepAngle = MAKEFIXED(90,0); 
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lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE , 0 3 (PBUNDLE)&lb); 
GpiPartialArc (hPS 3 &lPtCenter,MAKEFIXED(1,0) 3 fxStartAngle 3 
MAKEFIXED(0,0)); 

GpiQueryCurrentPosition(hPS,(PPOINTL)&lStartPt); 

/* Draw the left highlighted outline of the bulb */ 
lb.lColor = CLR_WHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

/* Draw the right shadowed outline of the bulb */ 
fxStartAngle = MAKEFIXED(210 3 0); 
fxSweepAngle = MAKEFIXED(210 3 0); 
lb.lColor = CLR_DARKGRAY; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_COLOR 3 0 3 (PBUNDLE)&lb); 
GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 

GpiQueryCurrentPosition(hPS 3 (PPOINTL)&lEndPt); 

/* Fill the bulb of the thermometer with the supplied color */ 
arcparms.lP -= 4; 
arcparms.lQ -= 4; 

GpiSetArcParams(hPS 3 (PARCPARAMS)&arcparms); 
ab.lColor = IColor; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_COLOR 3 0 3 (PBUNDLE)&ab); 

GpiMove (hPS 3 &lPtCenter); 

GpiFullArc(hPS 3 DRO_FILL,MAKEFIXED(1,0)); 


/*.*\ 

Draw the reflection on the bulb 

\*.*/ 

arcparms.lP = (arcparms.lP * 3) / 4; 
arcparms.lQ = (arcparms.lQ * 3) / 4; 


GpiSetArcParams(hPS 3 (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(120 3 0); 
fxSweepAngle = MAKEFIXED(90 3 0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS 3 PRIM_LINE , LBB_TYPE 3 0 , (PBUNDLE)&lb); 

GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0,0)); 

lb.lColor = CLR_WHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS, PRIM_LINE, LBB_C0L0R \ LBB_TYPE, 0, (PBUNDL.E)&lb) ; 
GpiPartialArc (hPS 3 &lPtCenter 3 MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 
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arcparms.lP = (arcparms.lP * 2) / 3; 
arcparms.IQ = (ancparms.lQ * 2) / 3; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(120,0); 
fxSweepAngle = MAKEFIXED(90,0); 
lb.usType = LINETYPE_INVISIBLE■ 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0, (PBUNDLE)&lb) ; 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0,0)); 

lb.lColor = CLRJVHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
fxSweepAngle); 


/*.- . *\ 

Draw the sides 

\*.*/ 

/* Draw the right vertical side */ 
lb.lColor = CLR_DARKGRAY; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_COLOR,0,(PBUNDLE)&lb); 

GpiMove(hPS,(PPOINTL)&lEndPt); 
lPt.x = lEndPt.x; 

lPt.y = pRectl->yBottom + ((iBoxHeight * 95) / 100); 

GpiLine (hPS,&lPt); 

/* Draw the left vertical side */ 
lb.lColor = CLRJVHITE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R,0,(PBUNDLE)&lb); 
lPt.x = IStartPt.x; 

GpiMove(hPS,(PPOINTL)&lPt); 

GpiLine (hPS,&lStartPt); 

/*.-.*\ 

Draw the rounded top 

\*.-.*/ 

/* Reset the rectangle for drawing the rounded top */ 

BulbRectl.xLeft = IStartPt.x; 

BulbRectl.yBottom = pRectl->yBottom + (iBoxHeight * 90) / 100; 
BulbRectl.xRight = lEndPt.x; 

BulbRectl.yTop = pRectl->yTop; 

arcparms.lP = (BulbRectl.xRight - BulbRectl.xLeft) / 2L; 
arcparms.lQ = (BulbRectl.yTop - BulbRectl.yBottom) / 2L; 
GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 

/* Calculate the center point for the rounded top arc */ 
lPtCenter.x = BulbRectl.xLeft + arcparms.lP; 
lPtCenter.y = BulbRectl.yBottom + arcparms.lQ + 1; 
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/* Draw an invisble arc from current location to start angle */ 
fxStartAngle = MAKEFIXED(0,0); 
fxSweepAngle = MAKEFIXED( 120,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0),fxStartAngle, 
MAKEFIXED(0,0)); 

/* Draw the shaded side */ 
lb.lColor = CLR_DARKGRAY; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0).fxStartAngle, 
fxSweepAngle); 

/* Draw the highlighed side */ 
fxStartAngle = MAKEFIXED(120,0); 
fxSweepAngle = MAKEFIXED(60,0); 
lb.lColor = CLR_WHITE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_COLOR,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFlXED(1,0),fxStartAngle, 
fxSweepAngle); 

/* Draw the reflection */ 

arcparms.IP = (arcparms.lP * 3) / 4; 

arcparms.lQ = (arcparms.IQ * 3) / 4; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
fxStartAngle = MAKEFIXED(90,0); 
fxSweepAngle = MAKEFIXED(90,0); 
lb.usType = LINETYPE_INVISIBLE; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0).fxStartAngle, 
MAKEFIXED(0,0)); 

lb.lColor = CLRJVHITE; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs (hPS,PRIM_LINE,LBB_COLOR | LBB_TYPE,0,(PBUNDLE)&lb); 
GpiPartialArc (hPS,&lPtCenter,MAKEFIXED(1,0).fxStartAngle, 
fxSweepAngle); 

DrawTemperature(hPS,pRectl,IColor,IBackColor,IPercent); 
return (TRUE); 


MRESULT EXPENTRY ThermometerWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 
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RECTL Recti; 

HPS hps; 

ULONG ulColors; 


switch (msg) 

{ 

case WM_CREATE: 

/* Initialize the window extra bytes */ 
WinSetWindowULong (hWnd, QWL_LOWERRANGE, 0L); 
WinSetWindowULong (hWnd, QWLJJPPERRANGE, 0L); 
WinSetWindowULong (hWnd, QWL_VALUE, 0L); 
WinSetWindowULong (hWnd, QWL_C0L0R, 
MAKELONG(CLR_RED,CLR_PALEGRAY)); 
break; 


case THM_SETRANGE: 

WinSetWindowULong (hWnd, QWL_LOWERRANGE, (ULONG)mpl); 
WinSetWindowULong (hWnd 3 QWL_UPPERRANGE, (UL0NG)mp2); 
break; 


case THM_SETVALUE: 

/* Set the new value */ 

WinSetWindowULong (hWnd, QWL_VALUE, (ULONG)mpl); 

/* Query colors and thermometer size */ 
ulColors = WinQueryWindowULong (hWnd, QWL_COLOR); 
WinQueryWindowRect (hWnd, &Rectl); 

if (!(WinQueryWindowULong (hWnd, QWL_STYLE) & THS_NOPERCENT)) 

{ 

Recti.xRight = (Recti.xRight * 6) / 10; 

Recti.xLeft += (Recti.xRight / 5); 

} 

Recti.yTop--; 

/* Update the thermometer temperature */ 
hps = WinGetPS (hWnd); 

DrawTemperature (hps, &Rectl, (LONG)((SHORT)ulColors ), 

(LONG)(ulColors » 16), CalculatePercentage(hWnd)); 
WinReleasePS (hps); 
break; 

case THM_SETCOLOR: 

WinSetWindowULong (hWnd, QWL_C0L0R, (ULONG)mpl); 

WinlnvalidateRect (hWnd, NULL, FALSE); 

break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 
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/* Fill window with background color */ 
ulColors = WinQueryWindowULong (hWnd 3 QWL_COLOR); 

WinFillRect (hps, &Rectl, (LONG)(ulColors » 16)); 

if (!(WinQueryWindowULong (hWnd, QWL_STYLE) & THS_NOPERCENT)) 

{ 

DrawPercentages (hps, &Rectl); 

Recti.xRight = (Recti.xRight * 6) / 10; 

Recti.xLeft += (Recti.xRight / 5); 

} 

Recti.yTop--; 

DrawThermometer (hps, &Rectl, 0L, (LONG)((SHORT)ulColors), 

(LONG)(ulColors » 16), CalculatePercentage(hWnd)); 

WinEndPaint (hps); 
break; 

default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


The only global variable we have in this file is hModDLL. Although this is not used in 
this DLL, it is a good practice to save the module handle of the DLL in case it is ever 
needed. Both window classes will need to keep track of data specific to each control win¬ 
dow created. This will be stored in window extra bytes for each window. As we did in 
our sample program in Chapter 3, “Window Management,” we define the offsets to these 
values with our identifiers. A bevel window will need to keep track of its colors and thick¬ 
ness: 


#define QWL_COLORS 0 

#define QWS_THICKNESS QWL_C0L0RS + sizeof(ULONG) 

#define BEVELEXTRA QWS_THICKNESS + sizeof(USHORT) 

A thermometer window will need to keep track of its lower-and upper-range values, 
its current value, and its fill color: 


#define QWL_LOWERRANGE 
#define QWLJJPPERRANGE 
#define QWL_VALUE 
#define QWL_C0L0R 
#define THERMOMETEREXTRA 


0 

QWL_LOWERRANGE + sizeof(ULONG) 
QWL_UPPERRANGE + sizeof(ULONG) 
QWL_VALUE + sizeof(ULONG) 
QWL_C0L0R + sizeof(ULONG) 
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Our initialization entry point, InitializeControlDLL was defined in the 
CTLINIT.ASM file. Each instance of the DLL must register the classes of the controls 
defined so that they are available for the application to use. We use the ulTerminating 
flag to tell us whether the DLL is being initialized or terminated (if def statements are 
necessary because of differences among the compilers that the code supports): 

#ifdef IBMC 

ULONG _System _DLL_InitTerm (HMODULE hModule, 

ULONG ulTerminating) 

#else 

ULONG _stdcall InitializeControlDll (HMODULE hModule, 

ULONG ulTerminating) 

#endif 

{ 

BOOL bResult; 

if (ulTerminating & 0x01) 
return (FALSE); 
else 
{ 

/* Register the window control classes */ 
bResult = 

WinRegisterClass ( 

(HAB)0, BEVELCLASS, BevelWndProc, 

CS_HITTEST | CS_SIZEREDRAW, BEVELEXTRA) && 
WinRegisterClass ( 

(HAB)0, THERMOMETERCLASS, ThermometerWndProc, 
CS_SIZEREDRAW, THERMOMETEREXTRA); 

} 

/* Save the module handle when we get loaded. The module handle 
will be the same for all instances of the DLL */ 

hModDll = hModule; 

return ((ULONG)bResult); 

} 


The CenterWindow function is the same one we used in our DLLSAMP and 
MINIMDI applications. Refer to the message processing code for the WM_CREATE mes¬ 
sage in CONTROLS.C. This code begins with the line: 

case WM_CREATE: 

BevelWndProc is the heart of the bevel control. When a bevel window is created, we 
must initialize the window extra bytes and possibly size the bevel window. 
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If either the BVS_PREVID or BVS_PREVWINDOW styles are specified, we use the 
Win Query Window function to traverse the previous sibling windows and accumulate their 
sizes and positions. When that is complete, WinSetWindowPos is used to set the bevel 
window’s size and position. Remember that we must use the x and y Fields of the bevel 
for its thickness and the cx field to increase the bevel’s location and width to provide the 
gap between it and the sibling windows. 

When we receive the BVM_SETCOLOR message, we need to save the new colors and 
cause it to repaint with the new colors. WinlnvalidateRect is used to force the repaint: 

case BVM_SETC0L0R: 

/* L0USH0RT(mp1) == Border color 

HIUSH0RT(mp1) == Interior color */ 

WinSetWindowllLong (hWnd, QWL._C0L.0RS, (ULONG)mpl); 

/* Repaint bevel with new color */ 

WinlnvalidateRect (hWnd, NULL, FALSE); 
break; 

When we receive the BVM_SETTHICKNESS, we simply save the new thickness. Typi¬ 
cally, the thickness does not change, so we don’t force it to repaint; however, adding a 
call to WinlnvalidateRect would suffice: 

case BVM_SETTHICKNESS: 

WinSetWindowUShort (hWnd, QWS_THICKNESS, SHORT1FROMMP(mpl)); 
break; 

All the drawing is performed during the WM_PAINT message. We first query the col¬ 
ors and thickness from the control’s window extra bytes. Its style is queried from PM: 

ulColors = WinQueryWindowULong (hWnd, QWL_C0L0RS); 
ulThickness = (ULONG)WinQueryWindowUShort (hWnd, QWS_THICKNESS); 
ulStyle = WinQueryWindowULong (hWnd, QWL_STYLE) & 0X0000FFFF; 

Depending on the style, the various style flags are set for the call to WinDrawBorder. 
Our control makes use of several undocumented styles for the WinDrawBorder API. We 
query the rectangle of the control and paint it: 

WinQueryWindowRect (hWnd, &Rectl); 

WinDrawBorder (hps, &Rectl, ulThickness, ulThickness, 

L0USH0RT(ulColors), HIUSH0RT(ulColors), ulDrawStyle); 

Finally, we add code for the WM_HITTEST message. Notice that we registered the 
BEVELCLASS with CS_HITTEST. This allows our application to receive WMJHITTEST mes¬ 
sages. Without this style, PM would automatically send all mouse messages to the con¬ 
trol window. Because a bevel window is usually overlapping other sibling windows, the 
Z-order of these windows might prevent us from clicking any one of those sibling 



Real-World Programming 


for OS/2 2.1 


windows because the mouse messages would be directed to the bevel window. With the 
CS_HITTEST class style, we can respond to the WM_HITTEST message with HT_TRANSPARENT, 
which tells PM we don’t want mouse messages. They will then go to the next sibling 
window beneath the mouse pointer: 

case WM_HITTEST: 

/* Allow mouse message to pass through this window */ 
rnReturn = (MRESULT)HT_TRANSPARENT; 
break; 

Thermometer WndProc has little to its code, but provides all the logic for the 
thermometer control window. During the WM_CREATE message, the window extra bytes 
are initialized: 

case WM_CREATE: 

/* Initialize the window extra bytes */ 

WinSetWindowULong (hWnd, QWL_L0WERRANGE, 0L); 

WinSetWindowULong (hWnd, QWLJJPPERRANGE, 0L); 

WinSetWindowULong (hWnd, QWLJ/ALUE, ®L); 

WinSetWindowULong (hWnd, QWL_C0L0R, MAKELONG(CLR_RED,CLR_PALEGRAY)) 
break; 

The THM_SETRANGE processing merely stores the lower and upper ranges in the win¬ 
dow extra bytes. Again, because this is typically done only once, we don’t force a repaint, 
but WinlnvalidateRect would suffice: 

case THM_SETRANGE: 

WinSetWindowULong (hWnd, QWL_L0WERRANGE, (ULONG)mpl); 
WinSetWindowULong (hWnd, QWLJJPPERRANGE, (UL0NG)mp2); 
break; 

The THM_SETVALUE processing involves a little more. Upon receipt of this message, 
the value is stored in the window extra bytes and the fill color is retrieved. We must then 
update the thermometer with the new value. Our thermometer will be drawn in the ther¬ 
mometer window with its left edge at 20 percent of the window’s width and its right 
edge at 60 percent of the window’s width. 

We then call the DrawTemperature function presented in Chapter 6, “Presentation 
Spaces and Drawing”: 

case THM_SETVALUE: 

/* Set the new value */ 

WinSetWindowULong (hWnd, QWL_VALUE, (ULONG)mpl); 

/* Query colors and thermometer size */ 
ulColors = WinQueryWindowULong (hWnd, QWL_C0L0R); 
WinQueryWindowRect (hWnd, &Rectl); 

if (!(WinQueryWindowULong (hWnd, QWLJ3TYLE) & THS_NOPERCENT)) 

{ 
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Recti.xRight = (Recti.xRight * 6) / 10; 

Recti.xLeft += (Recti.xRight / 5); 

} 

Recti.yTop--; 

/* Update the thermometer temperature */ 
hps = WinGetPS (hWnd); 

DrawTemperature (hps, &Rectl, (LONG)((SHORT)ulColors), 
(LONG)(ulColors » 16), CalculatePercentage(hWnd)); 
WinReleasePS (hps); 
break; 


The CalculatePercentage function takes the current value and computes the per¬ 
centage value based on the lower and upper range. The WM_PAINT message processing is 
similar except that it must first paint the entire control and then call DrawPercentages 
to draw the tick marks with the percentage indicators. It then calls DrawThermometer, 
which draws the thermometer outline and then fills the thermometer by using the cur¬ 
rent percentage value: 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 

/* Fill window with background color */ 

ulColors = WinQueryWindowULong (hWnd, QWL_COLOR); 

WinFillRect (hps, &Rectl, (LONG)(ulColors » 16)); 

if (!(WinQueryWindowULong (hWnd, QWL_STYLE) & THS_NOPERCENT)) 

{ 

DrawPercentages (hps, &Rectl); 

Recti.xRight = (Recti.xRight * 6) / 10; 

Recti.xLeft += (Recti.xRight / 5); 

} 

Recti.yTop- -; 

DrawThermometer (hps, &Rectl, 0L, (LONG)((SHORT)ulColors), 

(LONG)(ulColors » 16), CalculatePercentage(hWnd)); 

WinEndPaint (hps); 

break; 


Next, we move to the MEMDLL DLL. The external interface for this DLL is quite 
different. The MEMDLL DLL does not provide controls, but implements a memory 
suballocation module that tracks the size of each suballocated memory object and also 
tracks all the shared memory suballocated memory objects in order to clean up memory 
upon the termination of the process. The MEMDLL.H file defines the functions pro¬ 
viding these services. 
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MEMDLL.H 

/* 

MemDLL Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 


PVOID 

EXPENTRY 

VOID 

EXPENTRY 

VOID 

EXPENTRY 

PVOID 

EXPENTRY 

VOID 

EXPENTRY 

VOID 

EXPENTRY 


PrivateAllocate (ULONG); 
PrivateFree (PVOID); 
PrivateQuery (PULONG,PULONG); 
SharedAllocate (ULONG); 
SharedFree (PVOID); 
SharedQuery (PULONG,PULONG); 


PrivateAllocate will suballocate a block of memory from a private memory ob¬ 
ject. The only parameter to this function is the size of the memory object to suballocate. 
PrivateFree will free a privately suballocated memory object. The only parameter to 
this function is the pointer to the memory object. Notice that the size of the memory 
object is not passed in as a parameter. This is because the MEMDLL. DLL will keep 
track of this information for each memory object. PrivateQuery will return the total 
amount of memory in the suballocation block and the total amount of memory that has 
currently been suballocated from that block. The first parameter is a pointer to a ULONG 
that will contain the allocation size of the suballocation block. The second parameter is 
a pointer to another ULONG that will contain the amount of memory that has been 
suballocated from the suballocation block. 

The functions SharedAllocate, SharedFree, and SharedQuery are identical in 
functionality and parameters except they reference a shared memory block that is being 
used for suballocation among multiple processes. 

Because we are defining both a private allocation block and a shared allocation block, 
we require both instance data and global data. In addition, we will need our initialization 
function to be called for each instance of the DLL. The definition (DEF) file for the 
MEMDLL. DLL looks like this. 


MEMDLL.DEF 

LIBRARY MEMDLL INITINSTANCE 

DESCRIPTION 'Memory DLL 1993 Blain, Delimon, & English' 
PROTMODE 


CODE 

DATA 


MOVEABLE 

MOVEABLE SINGLE SHARED 
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SEGMENTS 

_INSTANCEDATA 
_INSTANCEDATA 
c common 


EXPORTS 

PrivateAllocate @1 
PrivateFree @2 
PrivateQuery @3 
SharedAllocate @4 
SharedFree @5 
SharedQuery @6 


Like the CONTROLS.DLL, this one is defined as a library with instance initializa¬ 
tion: 

LIBRARY MEMDLL INITINSTANCE 

Because we require both types of data segments, the default data segment type will 
be global, and we specifically identify all segments that will be private for each instance: 

CODE MOVEABLE 

DATA MOVEABLE SINGLE SHARED 

SEGMENTS 

_INSTANCEDATA CLASS 1 FAR_DATA' NONSHARED PRELOAD 

_INSTANCEDATA CLASS 'DATA' NONSHARED PRELOAD 

C_common CLASS 1 BSS 1 NONSHARED PRELOAD 

Remember to check the output of your MAP file for the specific name for the seg¬ 
ments and class name as they may change depending on which compiler you are using. 
Our size functions are exported here assigning each a unique ordinal value. 

Because we have defined the DLL to be INITINSTANCE, our initialization entry 
point is defined as it was for the CONTROLS.DLL. 

MEMINIT.ASM 

; Memory DLL Initialization 

; Define the initialization/termination entry point for the 
; Memory DLL 

. 386p 

ifdef_TASM_ 

model flat,pascal 
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CLASS 1 FAR_DATA' NONSHARED PRELOAD 
CLASS ’DATA' NONSHARED PRELOAD 
CLASS 'BSS' NONSHARED PRELOAD 
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endif 



_TEXT 

SEGMENT 

EXTRN 

DWORD USE32 PUBLIC 'CODE' 
_InitializeMemDll:near 

if def 

MASM386_ 



ASSUME CS: FLAT, DS: FLAT, ES: FLAT 
endif 


DLLEntry: 

jmp _InitializeMemDll 

TEXT ENDS 

END JDLLEntry 


The initialization function for this DLL is named “initializeMemDLL” and will be 
called both when the DLL is loaded and when unloaded for each instance of the DLL. 

The instance data we need to maintain for each instance of the DLL is defined in the 
MEMINST.H file. 


MEMINST.H 


/* 


Memlnst Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


/* MemDLL instance data structure */ 
typedef struct tagINSTANCE_STRUCT 
{ 

PVOID pMemPrivate; 

PVOID pMemSharedHead; 

ULONG ulTotalAlloc; 

ULONG ulTotalSubAlloc; 

ULONG ulTotalSharedSubAlloc; 

} INSTANCEDATA_STRUCT; 


We maintain the handle to the base of the private memory suballocation block in 
pMemPrivate. pMemSharedHead contains the handle of the last suballocated shared 
memory object for each instance. The shared memory handles are maintained by using a 
linked list that we will look at shortly. The size of the private memory suballocation block 
is stored in ulTotalAlloc, whereas the total amount of each type of suballocated memory 
for each instance is maintained in ulTotalSubAlloc and ulTotalSharedSubAlloc. 

The instance data structure is instantiated and defined in the MEMINST.C file. 
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MEMINST.C 


/* 


Memory DLL Instance Data 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "meminst.h" 

#ifndef ZORTECH 

/* IBMC compiler defines data segments with #pragma data_seg */ 
#ifdef _IBMC_ 

#pragma data_seg ( _INSTANCEDATA ) 

#endif 

INSTANCEDATA_STRUCT InstanceData = 

{ 


NULL, 

/* 

pMemPrivate 

*/ 

NULL, 

/* 

pMemSharedHead 

*/ 

0L, 

/* 

ulTotalAlloc 

*/ 

0L, 

/* 

ulTotalSubAlloc 

*/ 

0L 

/* 

ulTotalSharedSubAlloc 

*/ 


}; 

#else 

/* Zortech Compiler does not have a command line switch to rename the 
data segment. Use the c_common data segment by not initializing 
InstanceData. */ 

INSTANCEDATA_STRUCT InstanceData; 

#endif 


This file is compiled with the data segment name of_IN STANCE DATA so that the DEF 
file can define it as NONSHARED. All instance data can now be referenced in the 
InstanceData structure. Each instance of the DLL will receive its private copy of this 
instance data structure. 

We now take a look at the code for the functions implementing the DLL. 

MEMDLL.C 

/* . 

Memory DLL 
Chapter 10 
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Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


/* 

Returned address is the allocated address plus the size of a 
memory object header. 

Private memory allocation stores the object size in the header. 

Shared memory allocation stores the object size in the header. 

It also maintains a linked list of the memory objects so that 
memory can be cleaned up if a process terminates without freeing 
all of its allocated shared memory. 

*/ 

#define INCL_D0S 
#define INCLJDOSERRORS 
#define INCL_WIN 

#include <os2.h> 

#include <stdio.h> 

#include "memdll.h" 

#include "meminst.h" 

#define PRIVATEALLOC 0x20000 /* 128 K */ 

#define SHAREDALLOC 0x40000 /* 256 K */ 

typedef struct tagPRIVATE_MEMORY_OBJECT 

{ 

ULONG ulSize; /* Size of memory object */ 

} PRIVATE_MEMORY_OBJECT; 

typedef PRIVATE_MEMORY_OBJECT *PPRIVATE_MEMORY_OBJECT; 

typedef struct tagSHARED_MEMORY_OBJECT 

{ 

PVOID pPrev; /* Previous memory object */ 

PVOID pNext; /* Next memory object */ 

ULONG ulSize; /* Size of memory object */ 

} SHARED_MEMORY_OBJECT; 

typedef SHARED_MEMORY_OBJEOT *PSHARED_MEMORY_OBJECT; 


/* Nonshared data in segment _INSTANCEDATA */ 
extern INSTANCEDATA_STRUCT InstanceData; 

/* Shared data placed into initialized variables data segment */ 
/* IBMC compiler defines data segments with #pragma data_seg */ 
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#ifdef IBMC 

#pragma data_seg (DATA32) 
#endif 

PVOID pMemShared = NULL; 
BOOL bFirstlnstance = TRUE; 
HMODULE hModDll =0; 


#ifdef IBMC 

ULONG _System _DLL_InitTerm (HMODULE hModule, ULONG ulTerminating) 
#else 

ULONG _stdcall InitializeMemDll (HMODULE hModule, ULONG ulTerminating) 
#endif 
{ 

BOOL bResult; 

if (ulTerminating & 0x01) 

{ 

PSHARED_MEMORY_OBJECT pMem = InstanceData.pMemSharedHead; 

/* Free all shared suballocated memory the app forgot to free */ 
while (pMem) 

{ 

PVOID pMemPrev = pMem->pPrev; 

if (IDosSubFreeMem (pMemShared, pMem, pMem->ulSize)) 
pMem = (PSHARED_MEMORY_OBJEOT)pMemPrev; 
else 
break; 

} 

/* Release access to semaphore used for shared memory 
serialization */ 

DosSubUnset (pMemShared); 

/* Free the private memory allocated for this instance */ 
DosFreeMem (InstanceData.pMemPrivate); 

return (FALSE); 

} 

else 

{ 

/* Allocate the private memory and initialize for suballocation */ 
bResult = !DosAllocMem ((PPVOID)&InstanceData.pMemPrivate, 
PRIVATEALLOC, PAG_READ j PAGJVRITE) && 

IDosSubSet (InstanceData.pMemPrivate, 

DOSSUB_INIT | DOSSUB_SPARSE_OBJ, PRIVATEALLOC); 


if (bResult) 

{ 
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if (bFirstlnstance) 

{ 

/* Allocate the shared memory and initialize for 

suballocation. Only allocate for first instance of DLL */ 
bFirstlnstance = FALSE; 
bResult = 

IDosAllocSharedMem ((PPVOID)&pMemShared, NULL, 

SHAREDALLOC, PAG_READ | PAG_WRITE | fSHARE) && 
IDosSubSet (pMemShared, 

DOSSUB_INIT | DOSSUB_SPAR$E_OBJ j DOSSUB_SERIALIZE, 
SHAREDALLOC); 

/* Free shared memory if an error occurred */ 
if (IbResult && pMemShared) 

DosFreeMem (pMemShared); 

} 

else 

{ 

/* Get access to the shared memory and the semaphore used 
for memory suballocation of shared memory. */ 
bResult = 

IDosGetSharedMem (pMemShared, PAG_READ j PAG_WRITE) && 
IDosSubSet (pMemShared, 

DOSSUB_SPARSE_OBJ \ DOSSUB_SERIALIZE, 

SHAREDALLOC); 

} 

} 

if (IbResult) 

{ 

/* Free private memory if an error occurred */ 
if (InstanceData.pMemPrivate) 

DosFreeMem (InstanceData.pMemPrivate); 

} 

} 

/* Save the module handle when we get loaded. The module handle 
will be the same for all instances of the DLL */ 

hModDll = hModule; 

return ((ULONG)bResult); 


PVOID EXPENTRY PrivateAllocate (ULONG ulSize) 

{ 

PVOID pMem; 

/* Add room for the memory object header */ 
UlSize += sizeof(PRIVATE_MEMORY_OBJECT); 
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/* Align on 8 byte boundary */ 
ulSize = (ulSize + 7) & 0XFFFFFFF8; 

if (IDosSubAllocMem (InstanceData.pMemPrivate, &pMem, ulSize)) 

{ 

/* Save size in memory object header */ 

((PPRIVATE_MEMORY_OBJECT)pMem)->ulSize = ulSize; 

/* Data starts immediately after the memory object header */ 
pMem = (PVOID)((ULONG)pMem + sizeof(PRIVATE_MEMORY_OBJECT)); 

/* Increment total suballocation of private memory */ 
InstanceData.ulTotalSubAlloc += ulSize; 

} 

else 

{ 

WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, 

"Private Memory Suballocation Failure", 

"Memory Thermometer", 

0 , MB_ERR0R | MB_OK); 
pMem = NULL; 

} 


return (pMem); 

} 


VOID EXPENTRY PrivateFree (PVOID pData) 

{ 

PPRIVATE_MEMORY_OBJECT pMem; 

ULONG ulSize; 


/* Set pointer to memory object header */ 
pMem = (PPRIVATE_MEMORY_OBJECT)((ULONG)pData - 

Sizeof(PRIVATE_MEMORY_OBJECT)) 


ulSize = pMem->ulSize; 


if (!DosSubFreeMem (InstanceData.pMemPrivate, pMem, ulSize)) 

/* Decrement total suballocation of private memory */ 
InstanceData.ulTotalSubAlloc -= ulSize; 

else 

WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, 

"Private Memory Free Failure", 

"Memory Thermometer", 

0, MB_ERR0R | MB_0K); 


return; 

} 
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VOID EXPENTRY PrivateQuery (PULONG pTotalAlloc, PULONG pTotalSubAlloc) 

{ 

*pT 0 talAll 0 C = PRIVATEALLOC; 

*pTotalSubAlloc = InstanceData.ulTotalSubAlloc; 
return; 

} 

PVOID EXPENTRY SharedAllocate (ULONG ulSize) 

{ 

PVOID pMem; 

/* Add room for the memory object header */ 
ulSize += sizeof(SHARED_MEMORY_OBJECT); 

/* Align on 8 byte boundary */ 
ulSize = (ulSize + 7) & 0XFFFFFFF8; 

if (IDosSubAllocMem (pMemShared, &pMem, ulSize)) 

{ 

/* Save size in memory object header */ 

((PSHARED_MEMORY_OBJECT)pMem)->ulSize = ulSize; 

((PSHARED_MEMORY_OBJEOT)pMem) ->pNext = NULL; 

((PSHARED_MEMORY_OBJEOT)pMem)->pPrev = 

InstanceData.pMemSharedHead; 

if (InstanceData.pMemSharedHead) 

((PSHARED_MEMORY_OBJ EOT)InstanceData.pMemSharedHead)->pNext = 

pMem; 

InstanceData.pMemSharedHead = pMem; 

/* Data starts immediately after the memory object header */ 
pMem = (PVOID)((ULONG)pMem + sizeof(SHARED_MEMORY_OBJEOT)); 

/* Increment total suballocation of shared memory */ 

InstanceData.ulTotalSharedSubAlloc += ulSize; 

} 

else 

{ „ ... 

WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, 

"Shared Memory Suballocation Failure", 

"Memory Thermometer", 

0, MB_ERROR 1 MB_0K); 

pMem = NULL; 

} 

return (pMem); 

} 

VOID EXPENTRY SharedFree (PVOID pData) 

{ 

PSHARED_MEMORY_OBJEOT pMem; 

ULONG ulSize; 
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/* Set pointer to memory object header */ 
pMem = (PSHARED_MEMORY_OBJECT)((ULONG)pData - 

Sizeof(SHARED_MEMORY_OBJECT)); 

ulSize = pMem->ulSize; 

if (pMem == InstanceData.pMemSharedHead) 

{ 

if (pMem->pPrev) 

((PSHARED_MEMORY_OBJECT)(pMem->pPrev))->pNext = NULL; 
InstanceData.pMemSharedHead = pMem->pPrev; 

} 

else 

{ 

((PSHARED_MEMORY_OBJECT)(pMem->pNext))->pPrev = pMem->pPrev; 
if (pMem->pPrev) 

((PSHARED_MEMORY_OBJECT)(pMem->pPrev))->pNext = pMem->pNext; 

} 

if (IDosSubFreeMem (pMemShared, pMem, ulSize)) 

/* Decrement total suballocation of private memory */ 
InstanceData.ulTotalSharedSubAlloc -= ulSize; 

else 

WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, 

"Shared Memory Free Failure", 

"Memory Thermometer", 

0, MB_ERROR | MB_OK); 

return; 

} 

VOID EXPENTRY SharedQuery (PULONG pTotalAlloc, 

PULONG pTotalSharedSubAlloc) 

{ 

*pTotalAlloc = SHAREDALLOC; 

*pTotalSharedSubAlloc = InstanceData.ulTotalSharedSubAlloc; 
return; 


For our application, the private suballocation block will allocate 128K, and the shared 
suballocation block will allocate 256K: 

#define PRIVATEALLOC 0x20000 /* 128 K */ 

#define SHAREDALLOC 0x40000 /* 256 K */ 

The DLL will track the size of each suballocation memory object. For private memory 
objects, this is done by suballocating an additional four bytes, storing the size at the 
beginning of the block, and returning a pointer starting immediately after the size. See 
Figure 10.14. 
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typedef struct tagPRIVATE_MEMORY_OBJECT 

{ 

ULONG ulSize; /* Size of memory object */ 

} PRIVATE_MEMORY_OBJECT; 

typedef PRIVATE_MEMORY_OBJECT *PPRIVATE_MEMORY_OBJECT; 


Figure 10.14. 
Tracking a private 
memory object. 


ulSize 


pMem- 



...+ 

...+ 


When an instance terminates, we free all the memory in the private suballocation 
block. For shared memory objects, it is a little more complicated. We cannot merely free 
the shared memory suballocation block because other processes may be sharing this block 
of memory. In addition to tracking the size of each object, we must keep track of all cur¬ 
rently suballocated memory objects for each process. This is done by using a linked list. 
Shared memory objects will have enough additional bytes allocated to store a 
SHARED_MEMORY_OBJECT header (see Figure 10.15): 

typedef struct tagSHARED_MEMORY_OBJECT 

{ 

PVOID pPrev; /* Previous memory object */ 

PVOID pNext; /* Next memory object */ 

ULONG ulSize; /* Size of memory object */ 

} SHARED_MEMORY_OBJECT; 

typedef SHARED_MEMORY_OBJECT *PSHARED_MEMORY_OBJECT; 


Figure 10.15. 
Tracking a shared 
memory object. 


InstanceData.pMemSharedHead 


pPrev 


pNext 


ulSize 


pMem 




pPrev 


pNext 


ulSize 


pMem- 


When a memory object is allocated, it is placed at the head of the list. 
InstanceData.pMemSharedHead will point to the last suballocated shared memory ob¬ 
ject. When a memory object is freed, it is removed from the linked list. Upon termina¬ 
tion, the linked list for the process is walked, and all unfreed shared memory is freed. 


*• -K’ 
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The returned address starts immediately after this header information. Notice that 
because of the way we have defined the PR I VATE_MEM0RY_0BJ ECT and 
SHARED_MEM0RYJ3BJECT, the size of a suballocated memory object can always be deter¬ 
mined by subtracting sizeof (ULONG) from the pointer. 

The global data segment for this DLL contains the handle for the shared memory 
block and a flag indicating whether this is the first DLL being initialized for the DLL. 
The instance data is referenced externally: 

/* Nonshared data in segment _INSTANCEDATA */ 
extern INSTANCEDATA_STRUCT InstanceData; 

/* Shared data placed into initialized variables data segment */ 

/* IBMC compiler defines data segments with #pragma data_seg */ 

#ifdef _IBMC_ 

#pragma data_seg (DATA32) 

#endif 

PVOID pMemShared = NULL; 

BOOL bFirstlnstance = TRUE; 

HMODULE hModDll = 0 ; 

The initialization function, InitializeMemDll, is a little more involved than pre¬ 
vious initialization functions. When the DLL is being initialized, we must allocate the 
private memory block and initialize it for suballocation: 

/* Allocate the private memory and initialize for suballocation */ 
bResult = IDosAllocMem ((PPVOID)&InstanceData.pMemPrivate, 
PRIVATEALLOC, PAG_READ | PAGJVRITE) && 

IDosSubSet (InstanceData.pMemPrivate, 

DOSSUB_INIT | DOSSUB_SPARSE_OBJ, PRIVATEALLOC); 


If this is the first instance, we allocate the shared memory block and initialize it for 
suballocation: 

if (bResult) 

{ 

if (bFirstlnstance) 

{ 

/* Allocate the shared memory and initialize for 

suballocation. Only allocate for first instance of DLL */ 
bFirstlnstance = FALSE; 
bResult = 

IDosAllocSharedMem ((PPVOID)&pMemShared, NULL, 

SHAREDALLOC, PAG_READ ] PAGJVRITE | fSHARE) && 
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IDosSubSet (pMemShared, 

DOSSUB_INIT | DOSSUB_SPARSE_OBJ \ DOSSUB_SERIALIZE, 
SHAREDALLOC); 

/* Free shared memory if an error occurred */ 
if (IbResult && pMemShared) 

DosFreeMem (pMemShared); 

} 

If this is not the first instance, we just gain access to the shared memory and the 
suballocation semaphore: 

else 

{ 

/* Get access to the shared memory and the semaphore used 
for memory suballocation of shared memory. */ 
bResult = 

!DosGetSharedMem (pMemShared, PAG_READ ] PAG_WRITE) && 
IDosSubSet (pMemShared, 

DOSSUB_SPARSE_OBJ | DOSSUB_SERIALIZE, 

SHAREDALLOC); 

} 

When InitializeMemDll is called for termination, the linked list of shared memory 
objects for the current instance is walked, and each object is freed. The instance then 
releases its use of the shared memory semaphore and frees the private memory block. This 
provides a fine memory cleanup feature. 

For private memory allocation, the implementation is not complicated. 
PrivateAllocate adds in the header size, aligns on an 8-byte boundary, and performs 
the suballocation. If successful, the size is stored in the memory object, the address is offset 
past this size, and the total is incremented. PrivateFree offsets the address back to the 
memory object size, frees the memory, and decrements the total. PrivateQuery merely 
returns the current allocation totals. 

Shared memory allocation is not much different except that it has the additional 
workload of maintaining the linked list for the current instance. 

Weve said enough about the DLLs. Let’s take a quick look at the application called 
THERMO. We won’t spend much time discussing the application because most of its 
features were discussed in earlier chapters. The application consists of a basic dialog that 
shows both private and shared memory suballocation, bevel control windows, and a ther¬ 
mometer control window that shows the percentage of private memory suballocation that 
has occurred. 
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THERMO.RC 

/* . 

Thermo Resource File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 


#include <os2.h> 

#include "thermo.h" 

#include "controls.h" 

ICON ID_APPNAME THERMO.ICO 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Thermometer / Memory DLL Application 

END 

rcinclude thermo.dig 
rcinclude ..\..\common\about.dig 


THERMO.DLG 


/* 


Thermometer Dialog File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE ID_APPNAME LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Memory Thermometer", ID_APPNAME, 53, 100, 260, 137, 
WS_VISIBLE | FS_BORDER | NOT FS_DLGBORDER, 

FCF_SYSMENU \ FCF_TITLEBAR | FCF_NOBYTEALIGN | FCF_TASKLIST 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 

CONTROL "", IDC_BEVEL1, 0, 0, 260, 137, BEVELCLASS, 
BVS_BEVELOUT | BVS_RECTANGLE | WS_VISIBLE 

LTEXT "Private Memory", -1, 8, 125, 61, 8 

LTEXT "Memory Handles", IDC_BEVEL2, 13, 113, 61, 8 
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LTEXT "Total Allocated", -1, 13, 104, 61, 8 

LTEXT "Total Suballocated", -1, 13, 95, 61, 8 

CONTROL IDC_PRIVATELIST, 86, 87, 50, 35, WC_C0MB0B0X, 

r»DO nDnDnniMMi TOT i IA/C flDOl ID 1 \A/Q TARQTfiP 1 



CBS DROPDOWNLIST | WS_GROUP | WS 

_TABSTOP 

i 

i 



WS_VISIBLE 






RTEXT 

"00000000", 

IDC_PRIVATEALLOC, 

91, 

104, 

CO 

8 

RTEXT 

"00000000", 

IDC_PRIVATESUBALLOC, 

91, 

95, 

37, 

8 

PUSHBUTTON 

"Allocate", 

IDB_PRIVATEALLOC, 

12, 

77, 

40, 

14 

PUSHBUTTON 

"Free", 

IDB_PRIVATEFREE, 

55, 

77, 

40, 

14 

PUSHBUTTON 

"Free All", 

IDB PRIVATEFREEALL, 

03 

03 

77, 

40, 

14 

CONTROL 

IDC BEVEL2 ! BVS_IDMASK, 5, 

3, 1 

0, 




BEVELCLASS, 

BVS_BEVELIN { BVS_RECTANGLE 




BVS_PREVID 

| WS_VISIBLE 





LTEXT 

"Shared Memory", -1, 

8, 

59 

63, 

8 

LTEXT 

"Memory Handles", IDC_BEVEL3, 

13, 

47 

59, 

8 

LTEXT 

"Total Allocated", -1, 

13, 

38 

61, 

8 

LTEXT 

"Total Suballocated", -1, 

13, 

29 

03 

LO 

8 

CONTROL 

"", IDC_SHAREDLIST, 86, 21, 50, 

35, 

WC_COMBOBOX 


CBS DROPDOWNLIST | WS GROUP | WS 

JTABSTOP 

1 



WS_VISIBLE 






RTEXT 

"00000000", 

IDC SHAREDALLOC, 

91, 

38 

CO 

8 

RTEXT 

"00000000", 

IDC_SHAREDSUBALLOC, 

91, 

29 

37, 

8 

PUSHBUTTON 

"Allocate", 

IDB SHAREDALLOC, 

12, 

11 

40, 

14 

PUSHBUTTON 

"Free", 

IDB SHAREDFREE, 

55, 

11 

40, 

14 

PUSHBUTTON 

"Free All", 

IDB SHAREDFREEALL, 

98, 

11 

40, 

14 

CONTROL 

IDC_BEVEL3 | BVS_IDMASK, 5, 

3, 1 

, 




BEVELCLASS, BVS_BEVELIN ] BVS_RECTANGLE | 
BVS_PREVID | WS_VISIBLE 


LTEXT “Private Memory Usage", IDC_BEVEL4, 164, 119, 

72, 8 

CONTROL IDC_THERMOMETER, 168, 38, 70, 78, 

THERMOMETERCLASS, WS_VISIBLE 
CONTROL IDC_THERMOMETER | BVS_IDMASK, 3, 2, 1, 0, 

BEVELCLASS, BVS_BEVELIN ] BVS_RECTANGLE | BVS_PREVID j 
WS_VISIBLE 

LTEXT "Thermometer Color", -1, 164, 24, 77, 8 

CONTROL IDC_THERM0C0L0R, 164, 13, 55, 12, WC_SPINBUTTON, 

SPBS_READONLY | SPBS_MASTER | 

SPBS_JUSTLEFT | SPBS_FASTSPIN j 
WS_GR0UP | WS_TABSTOP ] WS_VISIBLE 
CONTROL IDC_BEVEL4 | BVS_IDMASK, 4, 2, 1, 0, BEVELCLASS, 

BVS_BEVELOUT J BVS_RECTANGLE ] BVS_PREVID | WS_VISIBLE 
CONTROL -1, 3, 2, 1, 0, BEVELCLASS, 

BVS_BEVELIN | BVS_RECTANGLE | BVS_PREVWINDOW | 
WS_VISIBLE 

END 

END 
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The dialog makes extensive use of our BEVELCLASS control. A bevel is placed around 
the private memory, shared memory, and the thermometer. The dialog also defines a bevel 
around the bevel on the thermometer, and still another bevel around that bevel, each 
specifying a different gap. Remember that all units in this file are in dialog units and not 
pixels. 

THERMO.H 

/* . 

Thermo Header File 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 


#def ine ID_APPNAME 1 

#define IDC_BEVEL1 50 
#define IDC_BEVEL2 51 
#define IDC_BEVEL3 52 
#define IDC_BEVEL4 53 

#define IDC_PRIVATEALLOC 100 
#define IDC_PRIVATESUBALLOC 101 
#define IDC_PRIVATELIST 102 
#define IDC_SHAREDALLOC 103 
#define IDC_SHAREDSUBALLOC 104 
#define IDC_SHAREDLIST 105 
#define IDC_THERMOCOLOR 106 
#define IDC_THERMOMETER 107 

#define IDB_PRIVATEALLOC 200 
#define IDB_PRIVATEFREE 201 
#define IDB_PRIVATEFREEALL 202 
#define IDB_SHAREDALLOC 203 
#define IDB_SHAREDFREE 204 
#define IDB_SHAREDFREEALL 205 

#define IDM_ABOUT 300 


THERMO.DEF 

NAME THERMO WINDOWAPI 

DESCRIPTION 'Thermometer 1993 Blain, Delimon, & English' 

PROTMODE 
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HEAPSIZE 4096 

STACKSIZE 16384 

EXPORTS 

MainDlgProc @1 
AboutDlgProc @2 

This should be nothing new to you at this point. We now look at the application itself. 


THERMO.C 


/* 


Thermo Program 
Chapter 10 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_DOS 
#define INCL_WIN 

#include <os2.h> 

#include <stdio.h> 

#include "thermo.h" 

#include "memdll.h" 

#include "controls.h" 

#include "..\..\common\about.h" 

/* Exported Functions */ 

MRESULT EXPENTRY MainDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Local Functions */ 

VOID AddListltem (HWND,PVOID,ULONG); 

VOID FreeAllListltems (HWND,ULONG,BOOL); 

VOID FreeListltem (HWND,ULONG,BOOL); 

ULONG Parseltem (PSZ); 

VOID SetNumberField (HWND,ULONG,USHORT); 

VOID UpdateNumbers (HWND); 

/* Global Variables */ 

HAB hab; /* Handle to anchor block */ 

CHAR szTitle[64]; 

/* Table of colors */ 

CHAR szColors[15][10] = 
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{ 

"Black", 
"Blue", 
"Brown", 
"Cyan", 
"DarkBlue", 
"DarkCyan", 
"DarkGray", 
"DarkGreen", 
"DarkPink", 
"DarkRed", 
"Green", 
"Pink", 
"Red", 
"Yellow", 
"White" 

}; 


/* Array of pointers to color strings (for spinner control) */ 
PVOID pszColors[15] = 

{ 

&szColors[0], 

&szColors[1], 

&szColors[2], 

&szColors[3], 

&szColors[4], 

&szColors[5], 

&szColors[6], 

&szColors[7], 

&szColors[8], 

&szColors[9], 

&szColors[10], 

&szColors[11], 

&szColors[12], 

&szColors[13], 

&szColors[14] 

}; 

/* Table of color indexes matching the szColor entries */ 

SHORT sColorMap[15] = 

{ 

CLR_BLACK, 

CLR_BLUE, 

CLR_BR0WN, 

CLR_CYAN, 

CLR_DARKBLUE, 

CLR_DARKCYAN, 

CLR_DARKGRAY, 

CLR_DARKGREEN, 
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clrjdarkpink, 

CLR_DARKREDj 
CLR_GREEN, 

clr_pink, 

clr_red 3 

clr_yellow 3 

CLR_WHITE 

}; 


/* Undocument menu message */ 

#define MM_QUERYITEMBYPOS 0x01f3 

#define MAKE_16BIT_P0INTER(p) \ 

((PVOID)MAKEULONG(LOUSHORT(p) 3 (HIUSHORT(p) «3) | 7)) 


int main() 

{ 

HAB hab; 

HMQ hmq; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab 3 0); 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle) 3 szTitle); 

WinDlgBox (HWND_DESKTOP, HWND_DESKTOP, MainDlgProc, 0, 

ID_APPNAME, NULL); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 

} 

VOID AddAboutToSystemMenu(HWND hWndFrame) 

{ 

MENUITEM mi; 

HWND hWndSysSubMenu; 

WinSendMsg (WinWindowFromID (hWndFrame, FID_SYSMENU), 
MM_QUERYITEMBYPOS, 0L, MAKE_16BIT_P0INTER(&mi)); 
hWndSysSubMenu = mi.hwndSubMenu; 
mi.iPosition = MIT_END; 
mi.atStyle = MIS_SEPARATOR; 
mi.afAttribute = 0; 
mi.id = -1; 

mi.hwndSubMenu = 0; 
mi.hltem = 0; 

WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), NULL); 
mi.afStyle = MIS_TEXT; 
mi.id m IDM_AB0UT; 
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WinSendMsg (hWndSysSubMenu, MM_INSERTITEM, MPFROMP (&mi), 
"About 
return; 


VOID AddListltem (HWND hWnd, PVOID pMem, ULONG ulCtllD) 

{ 

CHAR szNumber[9]; 

SHORT slndex; 

/* Convert address to hexadecimal string */ 
sprintf (szNumber, "%081x", (ULONG)pMem); 

WinUpper (hab, 0, 0, szNumber); 

/* Insert formatted memory address into listbox */ 
slndex = (SHORT)WinSendDlgltemMsg (hWnd, ulCtllD, LM_INSERTITEM, 
(MPARAM)LIT_END, szNumber); 

/* Select the item just inserted */ 

WinSendDlgltemMsg (hWnd, ulCtllD, LM_SELECTITEM 3 (MPARAM)slndex 3 
(MPARAM)TRUE); 

return; 

} 

VOID FreeAllListltems (HWND hWnd, ULONG ulCtllD, BOOL bPrivate) 

{ 

CHAR szNumber[9]; 

SHORT slndex; 

/* Query number of items in the listbox */ 

slndex = (SHORT)WinSendDlgltemMsg (hWnd, ulCtllD, LM_QUERYITEMCOUNT 3 
0L 3 0L); 


while (slndex--) 

{ 

/* Query the text of the last item in the listbox */ 
WinSendDlgltemMsg (hWnd, ulCtllD, 

LM_QUERYITEMTEXT 3 MPFR0M2SH0RT(slndex,9 ), szNumber); 

/* Convert text to address and free memory */ 
if (bPrivate) 

PrivateFree ((PVOID)Parseltem (szNumber)); 
else 

SharedFree ((PVOID)Parseltem (szNumber)); 


/* Delete all items in the listbox */ 

WinSendDlgltemMsg (hWnd, ulCtllD, LM_DELETEALL, 0L, 0L); 
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return; 

} 

VOID FreeListltem (HWND hWnd, ULONG ulCtllD, BOOL bPrivate) 

{ 

CHAR szNumber[9]; 

SHORT slndex; 

/* Query the selected item in the listbox */ 

slndex = (SHORT)WinSendDlgltemMsg (hWnd, ulCtllD, LM_QUERYSELECTION, 
(MPARAM)LIT_FIRST 3 0L); 

if (slndex 1= LIT_NONE) 

{ 

/* Query the text of the selected item in the listbox */ 
WinSendDlgltemMsg (hWnd, ulCtllD, 

LM_QUERYITEMTEXT, MPFR0M2SH0RT(slndex 3 9), szNumber); 

/* Convert text to address and free memory */ 
if (bPrivate) 

PrivateFree ((PVOID)Parseltem (szNumber)); 
else 

SharedFree ((PVOID)Parseltem (szNumber)); 

/* Delete the selected item from the listbox */ 

WinSendDlgltemMsg (hWnd, ulCtllD, LM_DELETEITEM, (MPARAM)slndex, 
0L); 

} 

/* Select the first item in the listbox */ 

WinSendDlgltemMsg (hWnd, ulCtllD, LM_SELECTITEM, (MPARAM)0L, 

(MPARAM)TRUE); 

return; 

} 

ULONG Parseltem (PSZ szltem) 

{ 

ULONG CurPos = 0; 

ULONG ulMem = 0; 

/* Convert hexadecimal string to number */ 
for (; CurPos < 8; CurPos++) 
ulMem = ulMem*16 + 

((szItem[CurPos] <= '9') ? (szItem[CurPos] - '0') : 

(szItem[CurPos] - 'A' + 10)); 


return (ulMem); 

} 
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VOID SetNumberField (HWND hWnd, ULONG ulNumber, USHORT usCtllD) 

{ 

CHAR szNumber[9]; 

/* Convert number to hexadecimal string */ 
sprintf (szNumber, "%81x", ulNumber); 

Winllpper (hab, 0, 0, szNumber) ; 

/* Set the text of the control */ 

WinSetDlgltemText (hWnd, usCtllD, szNumber); 

return; 

} 

VOID UpdateNumbers (HWND hWnd) 

{ 

ULONG ulAlloc, 

ulSubAlloc, 
ulSharedAlloc, 
ulSharedSubAlloc; 

/* Query private memory allocation info */ 

PrivateQuery (&ulAlloc, &ulSubAlloc); 

/* Query shared memory allocation info */ 

SharedQuery (&ulSharedAlloc, &ulSharedSubAlloc); 

SetNumberField (hWnd, ulAlloc, IDC_PRIVATEALLOC); 

SetNumberField (hWnd, ulSubAlloc, IDC_PRIVATESUBALLOC); 

SetNumberField (hWnd, ulSharedAlloc, IDC_SHAREDALLOC); 

SetNumberField (hWnd, ulSharedSubAlloc, IDC_SHAREDSUBALLOC); 

/* Free and Free All buttons are enabled only if memory allocated */ 
WinEnableControl (hWnd, IDB_PRIVATEFREE, ulSubAlloc); 
WinEnableControl (hWnd, IDB_PRIVATEFREEALL, ulSubAlloc); 
WinEnableControl (hWnd, IDB_SHAREDFREE, ulSharedSubAlloc); 
WinEnableControl (hWnd, IDB_SHAREDFREEALL, ulSharedSubAlloc); 

/* Set private memory allocation amount as the thermometer value */ 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETVALUE, 

(MPARAM)ulSubAlloc, 0L); 

return; 

} 


MRESULT EXPENTRY MainDlgProc (HWND hWnd, ULONG msg, 

MPARAM mp2) 


{ 


MPARAM mpl, 
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BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

PVOID pMem; 

ULONG ulAlloc, 

ulSubAlloc; 

switch (msg) 

{ 

case WM_INITDLG: 

/* Center the dialog on the screen */ 

CenterWindow (hWnd); 

/* Add the About menu item to the system menu */ 
AddAboutToSystemMenu (hWnd); 

/* Set the thickness of the border around the dialog */ 
WinSendDlgltemMsg (hWnd, IDC_BEVEL1, BVM_SETTHICKNESS, 
(MPARAM)4, 0L); 


/* Query the suballocation info to set thermometer range */ 
PrivateQuery (&ulAlloc, &ulSubAlloc); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM__SETRANGE, 0L, 
(MPARAM)ulAlloc); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER , THM_SETVALUE, 0L, 0L); 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETCOLOR, 

(MPARAM)MAKELONG(CLR_RED, CLR_PALEGRAY), 0L); 

/* Initialize the memory numbers */ 

UpdateNumbers (hWnd); 

/* Initialize the thermometer color spinner control */ 
WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR, SPBM_SETTEXTLIMIT 3 
(MPARAM)9L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR 3 SPBM_SETARRAY, 

(MPARAM)pszColors, (MPARAM)15L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR 3 SPBM_SETCURRENTVALUE 3 
(MPARAM)12L, (MPARAM)0L); 

/* Set the focus to the first pushbutton */ 

WinSetFocus (HWNDJDESKTOP, 

WinWindowFromID (hWnd, IDB_PRIVATEALLOC)); 
break; 

case WM_C0NTR0L: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_THERM0C0L0R: 

if (HIUSHORT(mpl) == SPBN_ENDSPIN) 

{ 


ULONG ulSelect; 
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/* Query selection index from spinner */ 
WinSendDlgltemMsg (hWnd, IDC_THERM0C0L0R, 
SPBM_QUERYVALUE, (MPARAM)&ulSelect, 0L); 

/* Set the current color of the thermometer */ 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER , THM_SETC0L0R, 

(MPARAM)MAKELONG(sColorMap[ulSelect], CLR_PALEGRAY), 
0L); 

} 

break; 

} 

break; 

case WM_COMMAND: 
case WM_SYSCOMMAND: 

switch (SH0RT1FROMMP(mpl)) 

{ 

case IDB_PRIVATEALLOC: 

/* Allocate an arbitrary amount of 1000 bytes */ 
if ((pMem = PrivateAllocate (1000L)) != 0) 

AddListltem (hWnd, pMem, IDC_PRIVATELIST); 
break; 

case IDB_PRIVATEFREE: 

FreeListltem (hWnd, IDC_PRIVATELIST, TRUE); 
break; 

case IDB_PRIVATEFREEALL: 

FreeAllListltems (hWnd, IDC_PRIVATELIST 3 TRUE); 
break; 

case IDB_SHAREDALLOC: 

/* Allocate an arbitrary amount of 1000 bytes */ 
if ((pMem = SharedAllocate (1000L)) != 0) 

AddListltem (hWnd, pMem, IDC_SHAREDLIST); 
break; 

case IDB_SHAREDFREE: 

FreeListltem (hWnd, IDC_SHAREDLIST , FALSE); 
break; 

case IDB_SHAREDFREEALL: 

FreeAllListltems (hWnd, IDC_SHAREDLIST, FALSE); 
break; 

case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
break; 
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case SC_CL0SE: 

WinDismissDlg (hWnd, FALSE); 

bHandled = TRUE; 

break; 

default: 

bHandled = (msg == WM_COMMAND); 

} 


/* If button was pressed then update the numbers */ 
if (msg == WM_COMMAND) 

UpdateNumbers (hWnd); 

break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


A bevel is defined around the entire edge of the dialog window. The thickness of this 
bevel is set during the WM_INITDLG message: 

/* Set the thickness of the border around the dialog */ 
WinSendDlgltemMsg (hWnd, IDC_BEVEL1, BVM_SETTHICKNESS, (MPARAM)4, 0L); 

The thermometer control is also initialized during the WM_INITDLG message. 
PrivateQuery is called to get the size of the private suballocation block, and this value is 
used to initialize the thermometer control: 

/* Query the suballocation info to set thermometer range */ 
PrivateQuery (&ulAlloc, &ulSubAlloc); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETRANGE, 0L, 
(MPARAM)ulAlloc); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETVALUE, 0L, 0L); 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETCOLOR, 

(MPARAM)MAKELONG(CLR_RED, CLR_PALEGRAY), 0L); 

The color of the thermometer can be changed by selecting a new color in the spinner 
control. The spinner control is initialized with the array of available colors: 

/* Initialize the memory numbers */ 

UpdateNumbers (hWnd); 
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/* Initialize the thermometer color spinner control */ 
WinSendDlgltemMsg (hWnd, IDC_THERM0C0L0R, SPBM_SETTEXTLIMIT, 
(MPARAM)9L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR, SPBM_SETARRAY, 
(MPARAM)pszColors, (MPARAM)15L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR, SPBM_SETCURRENTVALUE, 
(MPARAM)12L, (MPARAM)0L); 


When the SPBN_ENDSPIN notification is received, the current value is queried, and 
the thermometer color is changed with the THM_SETCOLOR message: 

case WM_C0NTR0L: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_THERMOCOLOR: 

if (HIUSHORT(mpl) == SPBN_ENDSPIN) 

{ 

ULONG ulSelect; 

/* Query selection index from spinner */ 

WinSendDlgltemMsg (hWnd, IDC_THERMOCOLOR, 

SPBM_QUERYVALUE, (MPARAM)&ulSelect, 0L) ; 

/* Set the current color of the thermometer */ 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETCOLOR, 

(MPARAM)MAKELONG(sColorMap[ulSelect], CLR PALEGRAY) 
0L); 

} 

break; 

} 

break; 


The Allocate button will cause memory object to be suballocated by calling either 
PrivateAllocate or SharedAllocate. The returned address is inserted into the appro¬ 
priate list box. The Free button will free the currently selected memory object by calling 
either PrivateFree or SharedFree. The Free All button will free all memory objects in 
the appropriate list box by calling either PrivateFree or SharedFree for each entry in 
the list box. After any one of these commands is processed, the numbers are updated by 
calls to PrivateQuery and SharedQuery in the UpdateNumbers function. At the end of 
the UpdateNumbers function, the current value of the thermometer is set. 

/* Set private memory allocation amount as the thermometer value */ 
WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETVALUE, 

(MPARAM)ulSubAlloc, 0L); 
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These two DLLs have been written to demonstrate the basics for creating general 
purpose DLLs. The CONTROLS.DLL demonstrated how to create private control classes 
and allow any application to use those controls. The MEMDLL DLL demonstrated how 
to use both instance and global data in managing memory and how to use the Initializa¬ 
tion/Termination function to perform memory cleanup. 







Printing 


Introduction 


With only a few exceptions, most programs produce some type of printed output. One 
of the more time-consuming aspects of application development is ensuring that it prints 
correctly on a multitude of devices. In an effort to simplify the programmatic and user 
interaction with printers, OS/2 2.1 introduced the concept of a print object to 



application printing. A print object is a logical print destination that is 
comprised of a spooler, a printer driver, and a queue driver. This 
Ig* object manages all aspects of a print job and adds new flexi¬ 
bility to OS/2. 
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This chapter is intended to provide you with a framework for interacting with the 
OS/2 print subsystem. To that end, this chapter shows you how to build a sample print¬ 
ing application called PRNT, which demonstrates printer selection, page display, form 
enumeration, and printing. Before examining how printing works in OS/2 2.1, however, 
it’s useful to briefly review printing in DOS, Windows 3.x, and OS/2 1.x . 

Some Printing Backgrounds The DOS Days 

Printing during the DOS days was very basic—text output was sent to a physical port 
(such as LPT1) as a series of characters. When the printer’s buffer filled up, the applica¬ 
tion waited for the printer to catch up before sending more data, and the printer became 
a large bottleneck. With this came a tremendous burden. DOS applications that wanted 
to produce printed output other than basic text were required to write what amounted to 
a printer driver for each device it wished to support. Most applications relied on a set of 
drivers created and distributed by the software application s programmers. Raster print¬ 
ers often require special escape sequences for changing such items as font size, and graph¬ 
ics output on these printers was even more involved. Other devices such as PostScript or 
LaserJet printers required a completely different form of data. Also, the displayed text 
and graphics often had very little resemblance to the printed output. 

The support burden for this was phenomenal. Printer manufacturers, of course, did 
not time the release of their new printers around software, so some incompatibility be¬ 
tween revision levels was always likely, and the programming teams needed to support 
all these different printers was quite large. New printing technology, then as now, was 
being created all the time, so the shipping version of your software was always guaran¬ 
teed to be out of date in comparison to the available printers. 

Device Independence 

One of the benefits that a device-independent programming interface provides is device 
support. This device independence really began to take hold in the IBM-compatible pro¬ 
gramming world with the release of ^Windows. Windows removed the direct interaction 
between display and print hardware from the application. OS/2 extends this device inde¬ 
pendence by providing such things as logical printers and logical queues. 

Chapter 6, “Presentation Spaces and Drawing,” discussed the device-independent 
model the GPI provides. By using various presentation space handles, an application 
could call the same API function to produce output on the display and the printer. A 
printer driver provides the link from the graphics engine to a physical output device. The 
term printer driver is used to refer to a software component that controls various output 
devices such as plotters and printers. It is the printer driver’s job to communicate the 
request to the hardware in a form it can understand. A printer driver is a stand-alone 
component that provides specific entry points that are called by the operating system. 
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Although a vendor could write its own printer driver, many popular devices were sup¬ 
plied with the base system. 

Printing Under OS/2 1.x and Windows 3.x 

Before printing to a device can begin, a list of available devices must be determined. In 
both OS/2 1.x and Windows, the currently installed printer device drivers could be de¬ 
termined by querying entries from a system initialization file. Of the installed drivers, 
one is considered the default. The default driver is identified by a separate entry in the 
initialization file. In both environments, the entries are maintained through a print man¬ 
ager or control program. 

The Windows system configuration files are simple text files with a well-documented 
format. This encourages users and programs to modify the system settings to suit their 
needs. The OS/2 system configuration files are written in a binary format and cannot be 
modified with a text editor, which makes modifications more difficult. In either case, the 
driver information is returned from system functions in a format that requires parsing 
before the information is useful. Included in the returned strings are the printer driver 
physical name and the hardware port to which the device is connected. Once installed, a 
printer driver can be configured from a printer properties dialog box. This dialog is part 
of the printer driver and allows setting of hardware personalities, along with default page 
orientation and size. A single PostScript printer driver, for example, can support 50 or 
more different brands and models of printer hardware. 

In addition to printer properties, OS/2 introduced the concept of job properties. Job 
properties are properties that affect the appearance of a single print job without changing 
system-wide settings. The page orientation and number of copies are typical job proper¬ 
ties. Each printer driver defines a second dialog that allows job properties to be set on an 
application-by-application basis. 

OS/2 2.1 Print Objects 

When a printer driver is installed in OS/2 2.1, it becomes a print object, which, from the 
end-user perspective, is in fact the printer. The name and hardware port connections can 
be modified on the settings page of the print objects notebook by the user. Although the 
print object is one logical unit, it is actually comprised of a queue driver and a printer 
driver. 

In OS/2 1.x, a printer can be configured optionally with a queue if the user desires. 
In 2.1, all print objects include a queue. The default queue driver PMPRINT, or queue 
processor as it is sometimes, called is responsible for distributing print jobs to a single 
printer or among multiple printers. Print objects have the flexibility to allow multi¬ 
ple printers to be connected to a single queue. In businesses where many printers are 
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available, this makes more efficient use of available printers possible. It allows the load to 
be balanced among multiple printers simultaneously. Multiple print queues may be con¬ 
nected to a single printer to allow printer sharing. A second queue processor, PM PLOT, is 
intended for use with plotters. It contains a reverse clipping engine that clips out over¬ 
lapping objects before output is sent to the plotter. 

Spooler 

The spooler is a system object comprised of one or more queues that hold print jobs while 
awaiting an output resource to become available. Spooling a print job allows it to be printed 
as a background task when the printer becomes available. Meanwhile applications con¬ 
tinue their processing. Spooling also allows system output resources to be shared among 
competing applications. 

Determining Installed Devices 

In OS/2 1 .x, determining the installed and default print devices requires that the sys¬ 
tem initialization files be read. The WinQu e ry P rof ileSt ring or the later 
PrfQueryProf ileString functions are used to enumerate these devices. This requires 
an intimate knowledge of the format and location of the data stored in the system INI 
files. 

OS/2 2.1 introduced a new API to interact with print objects and print jobs. The 
spooler API allows an easier method of querying all of the same items previously returned 
from the profile API. Many applications still use the old profile functions to identify 
installed devices. Although the format of data has not changed from 1.x to 2.1, these 
programs should be updated to eliminate dependencies on what are now undocumented 
entries in the system INI files. To ease the conversion of existing applications to the new 
spooler API, a cross-reference of the old and new functions has been provided at the end 
of this chapter. 

SplEnumQueue 

The SplEnumQueue function returns a list of printers on a local or remote workstation. 
Four levels of details, 3 through 6, can be returned by the function. A corresponding 
structure is defined for each level of detail. The function is defined as follows: 

SplEnumQueue (pCompName,ulLevel,pBuffer,ulBuffSize,pulReturned, 
pulTotal,pulNeeded,pRes) 
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PSZ 

pCompName 

Pointer to a null-terminated 
string that identifies the com¬ 
puter to query for installed 
printers. NULL may be used 
to query the local machine. 

ULONG 

ulLevel 

Defines the level of detail 
required, which may be one of 
the following: 


3 pBuffer 

Points to an array of PRQINF03 
structures. 


4 pBuffer 

Points to an array of PRQINF03 
structures, each of which is 
followed by an array of 
PRJINF02 structures. The 
number of the PRQINF02 
structures is found in the 
cjobs field of the preceding 
PRQINF03 structure. 


5 pBuffer 

Points to a null-terminated 
queue name. 


6 pBuffer 

Points to an array of PRQINF06 
structures. 

PVOID 

pBuffer 

Pointer to a memory buffer as 
defined by the ulLevel parameter. 

ULONG 

ulBuffSize 

Size in bytes of the memory 
pointed to by pBuffer. 

PULONG 

pulReturned 

Pointer to a long, which upon 
return contains the number of 
entries returned. For level 4 
this indicates the number of 
PRQINF03 structures but not 
the PRJINF02 structures. 

PULONG 

pulTotal 

Pointer to a long, which upon 
return contains the total entries 
available. 

PULONG 

pulNeeded 

Pointer to a long, which upon 
return indicates the number 
of bytes required to hold all 
information. 

PVOID 


A reserved parameter that must 
be NULL. 
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Calling the function with the p Buff er field set to NULL queries the numbers of en¬ 
tries and the size required to hold the data. Because the queue structures contain pointers 
to some of the returned data, pulNeeded will not be equal to pulTotal times the size of 
the returned structure. The data that is pointed to begins immediately after the last struc¬ 
ture in the array. Therefore, the memory buffer allocated for the queue entries should 
always be allocated dynamically to avoid buffer overrun. 

For info levels 3, 4, and 6, an array of PRQINF03 or PRQINF06 structures are re¬ 
turned. The PRQINF03 structure is identical to PRQINF06 (without the last two fields, 
which are pointers to remote queue and computer names). The structure contains a pointer 
to the physical queue name as well as the queue description. The contents of these struc¬ 
tures may be used to display a list of print destinations and create printer device contexts 
(DC) using the DevOpenDC function. Because you will be using this structure through¬ 
out the chapter and the sample program, let’s take a closer look. 


PRQINF03/PRQINF06 

PSZ pszQueueName 


USHORT uPriority 


USHORT uStartTime 

USHORT uUntilTime 


USHORT fsType 


Pointer to a null-terminated 
string that is the physical queue 
name. This name corresponds to 
a subdirectory under the spooler 
directory (typically, c:\spool). It 
also appears on the view page of 
the queue settings dialog. This 
value cannot be changed. 

This parameter identifies the 
priority assigned to the queue. It 
may range from 1 to 9 (with 1 
assigned as the highest priority). 
These parameters indicate the 
active hours of a queue, which 
ranges from uStartTime to 
uUntilTime. The format of both 
fields is the number of minutes 
past midnight. 

This value identifies the queue 
type that is set via the queue 
options on the queue settings 
notebook. It may be one of the 
following: 
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PRQ3_TYPE_RAW 

Output is spooled in printer- 
specific format. 
PRQ3_TYPE_QP_BYPASS 

The spooler is configured to 
bypass the queue processor and 
send data directly to the printer 
driver. 

PSZ 

pszSepFile 

Pointer to a null-terminated 
string that contains the path of a 
file that contains a separator file 
page. If set, the page(s) defined in 
the file are output between print 
jobs. If no pages are desired, 
NULL may be specified. 

PSZ 

pszQueueProc 

Pointer to a null-terminated 
string that identifies queue 
processor for this queue. Current 
PMPRINT and PMPLOT are 
the only two processors defined. 

PSZ 

pszQueueParam 

Pointer to a null-terminated 
string that contains queue 
parameters. 

PSZ 

pszComment 

Pointer to a null-terminated 
string that contains the user- 
supplied queue description. This 
value is the descriptive name 
given by the user that appears in 
the icon text window and the title 
entry on the general page of 
printer settings. 

USHORT 

fsStatus 

This field contains flags that 
identify the status of the queue. It 
may be one of the following: 

PRQ3_PAUSED 

The queue has been held. 

PRQ3JPENDING 

The queue is pending deletion. 


569 



Real-World Frogramming for KJ&/Z* 2.1 


The number of jobs in the queue. 
Pointer to a null-terminated 
string that contains the print 
devices connected to this queue. 
This is often, but not always, 
equal to the queue name. 

Pointer to null-terminated string 
that identifies the printers 
connected to the queue. It is 
in the form <physical driver 
name>. <driver description. For 
example, if you install the HP 
LaserJet IHSi version of the 
PostScript driver, the entry is as 
follows: 

PSCRIPT.HP LaserJet IHSi 
PS v52_3 

PSZ pDriverData Pointer to a device-specific block 

of data that identifies the default 
queue properties. 

PRQINF06 Only 

PSZ pszRemoteComputerName Pointer to a null-terminated 

string that contains the name 
of a remote computer for which 
this queue has a local alias. 

PSZ pszRemoteQueueName Pointer to a null-terminated 

string that contains the name 
of a remote queue for which 
this queue is a local alias. 

The Queue and Printer details dialog box in the PRNT sample application provided 
with this book displays most of the fields of the PRQINF03 structure (along with other 
device information). When you select the printer information menu option on the Dis¬ 
play menu, the installed print objects are enumerated using the SplEnumQueue function. 
The queue descriptions from the pszComment field are added to the upper-left list box. 
Under that list box, several windows display the queue status, jobs, and a start and stop 
time. Three other entries display queue strings as follows: 


USHORT cjobs 

PSZ pszPrinters 


PSZ pszDriverName 
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Label in the dialog 

Queue Name: 
Default Device: 
Print Devices: 


Field in PRQINF03 

pszName 

pszDriverName 

pszPrinters 


Identifying the Default Print Object 

The new spooler API is still missing one function: SplQueryDef aultQueue. Determin¬ 
ing the system default print object must be done using “the old way” by querying an entry 
in the system INI file. The physical name of the default queue may be found in the QUEUE 
entry of the PM_SP00LER section of the user INI file. Using the physical name, a PRQINF03 
structure may be retrieved by calling the SplQueryQueue function. The physical name 
returned from the profile query ends in a semicolon. The semicolon should be removed 
before passing the name to the SplQueryQueue function. The following code fragment 
shows both functions being called: 

/* Query the default printer */ 

ulSize = PrfQueryProfileString(HINI_PR0FILE,"PM_SP00LER","QUEUE", 

0,szTemp,MAX_BUFF); 

if (ulSize) 

{ 

pStr = strchr(szTemp,'; 1 ); 

*pStr = 0; 

SplQueryQueue(0,szTemp,3,0,0,&ulNeeded); 

if (ulNeeded && !(DosSubAlloc(pMem,(PPV0ID)&pPrq3,ulNeeded))) 

{ 

SplQueryQueue(0,szTemp,3,pPrq3,ulNeeded,&ulNeeded); 

} 

} 


Printer versus Job Properties 

When I reviewed the history of printing in DOS, Windows, and OS/2 1 .x earlier in this 
chapter, I said that OS/2 introduced the concept of job properties. This, however, is not 
entirely true. 

Windows 3.x added a function that printer drivers were required to implement in 
order to be considered 3.x-compliant. This function (ExtDeviceMode) allowed an appli¬ 
cation to retrieve and save printer configuration data, which could later be passed into a 
function that created a device context. 

The ExtDeviceMode function allowed, but did not require, applications to imple¬ 
ment printer job properties. What OS/2 brought to the table was a formalized job prop¬ 
erties implementation. Printer drivers are required to implement a printer properties dialog 
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and a job properties dialog. These are often two entirely separate dialog boxes for listing 
and choosing printer characteristics. The printer properties may be displayed by double¬ 
clicking on the printer driver icon on the printer driver page of any printer settings note¬ 
book. The job properties may be selected by selecting the job properties pushbutton on 
the same page of the notebook. 

Printer Properties 

Printer properties define a base configuration for a print device. Hardware configuration 
of paper trays and installed font cartridges are typically found on this dialog. However, it 
may also include nonhardware items such as default paper orientation. Changes made in 
this dialog are written to the system INI file. Future jobs printed to this print object are 
affected by these settings. The saved settings are those which the pD river Data field of 
the PRQINF03/6 structure points to. An application does not post this dialog. 

Job Properites 

Job properties are properties that affect the appearance of a single print job without chang¬ 
ing system-wide settings. Page orientation and number of copies and pages are typical 
items found on a job properties dialog. The job properties dialog may look identical to 
the printer properties dialog (as it does for the Epson driver) or it may be different. In 
either case, changes made in the job properties dialog are not saved to an INI file. Unless 
the application saves the modified driver data, the changes are lost. 

Posting the Job Properties Dialogs 
DevPostDeviceModes 

In Windows, the function that displays the configuration dialog is not a Windows 
API. It is actually a function exported from the printer driver. OS/2 has provided 
the DevPostDeviceModes system function, which handles the task of interacting 
with the configuration functions of all drivers. DevPostDeviceModes is used for retriev¬ 
ing the current driver settings with or without displaying the job properties dialog. 
Perhaps the most difficult part of using the function is supplying the correct device 
names. The DevPostDeviceModes function is defined as follows: 

DevPostDeviceModes (hAB,pDriverData,pszDriverName, 
pszDeviceName,pszName,ulOption) 

HAB hAB Handle to anchor blocks returned 

from the Winlnitialize function. 
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pDriverData 


pszD riverN ame 


pszDevicename 


pszName 


Pointer to a memory block large 
enough to hold the printers 
DRIVDATA structure. The size 
in bytes of the DRIVDATA is 
returned if this parameter is 

NULL. 

Pointer to a null-terminated 
string that contains the device 
driver name of the printer to 
query. This should be the por¬ 
tion that precedes the period 
in the string pointed to by the 
pszDriverName parameter in 
the PRQINF03 structure. 

Using the example from above: 

PSCRIPT.HP LaserJet IHSi PS 
v52_3. 

The supplied string would be 
PSCRIPT. 

Pointer to a null-terminated 
string that contains the device 
name of the printer to query. 

This should be the portion that 
follows the period in the string 
pointed to by the pszDriverName 
parameter in the PRQINF03 
structure. Using the example 
from above: 

PSCRIPT.HP LaserJet IHSi PS 
v52_3. 

The supplied string would be HP 
LaserJet IHSi PS v52_3. 

Pointer to a null-terminated 
string that contains the printer 
device name. This should be the 
same as the pszPrinters field of 
the PRQINF03 structure. 
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ULONG ulOption A flag that tells the driver what 

action to take. It may be one of 
the following: 

DBDMJPOSTJOBPROP. 

The job properties dialog is 
posted, and the updated driver 
data is returned when the user 
closes the dialog. 
DBDM_QUERYJOBPROP. 

The current driver data is 
returned without displaying 
the job properties dialog. 

If successful, the function returns DEV_0K indicating that the returned driver data is 
valid. If the function fails, the driver data could be invalid and should not be used. By 
using the DPDM_QUERYJOBPROP flag, the current driver data is returned without display¬ 
ing the dialog box. If the DBDM_POSTJOBPROP flag is used, the dialog is displayed. The 
DevPostDeviceModes function, however, does not provide a method for determining 
how the dialog was dismissed. 

The PM documentation suggests that you always treat the returned data as if the OK 
button was selected. Another alternative is to save a copy of the driver data passed to the 
DevPostDeviceModes function and compare it with the returned data (replacing it if it 
is different). Because each device stores data in its own private format, it is invalid to pass 
the driver data to a different device. The get J ob_properties function in the sample 
application provides a good example of calling the DevPostDeviceModes. 

Once returned, the driver data may be supplied as input to a future call to 
DevPostDeviceModes. This causes the driver to display its configuration dialog with the 
same setting as when it was closed, assuming that the Cancel button was not selected. 
When an information or queued device context is created, the driver data should be passed 
in the DEVOPENSTRUC as input to DevOpenDC. This creates a DC with the desired job 
properties. 

Creating an Information Device Context 

Once the target print device is determined, an application needs to create an informa¬ 
tion device context, which can be used to determine device capabilities and physical di¬ 
mensions. With this information, you can create a representation of the target print page 
in your client window. The queue and printer details dialog in the PRT program queries 
and displays various values returned from the DevQueryCaps function for the selected 
driver. 




Chapter I I Printing 


Although Chapter 6 discussed the DevOpenDC function, it deferred information and 
print device contexts to this chapter. You may recall that the device context is the link 
between a presentation space and the physical device it represents. Associated with the 
device context is a presentation space where all drawing occurs. A “print” device context 
and an associated presentation allow output to occur on a device other than the display. 
The “print” device context is a general term for those of type OD_QUEUED or 0D_DIRECT. 
An information device context is basically the same as a “print” DC, except that no out¬ 
put occurs when the presentation space associated with it is drawn into. It allows your 
application to maintain a shadow of the current target print device and maintain a “what 
you-see-is-what-you-get” (WYSIWYG) display. An info DC may be created by passing 
the 0D_INF0 flag as the type parameter to DevOpenDC function and initializing the 
DEVOPENSTRUCT correctly. The fields of the DEVOPENSTRUC as they apply to creating DCs 
of type 0D_INF0 are as follows: 

Pointer to a null-terminated 
string that is the port name the 
driver is connected to. The port 
may be queried using the 
SplQueryDevice function. If 
successful, the pszLogAddr of the 
returned PDRINF03 structure 
contains the port name. This 
field should only be set to the 
port name when creating an 
info DC. 

Pointer to a null-terminated 
string that contains the device 
driver name. This should be the 
portion that precedes the period 
in the string pointed to by the 
pszDriverName parameter in 
the PRQINF03 structure. 

Using the example from above: 

PSCRIPT.HP LaserJet IHSi PS 
v52_3 . 

The supplied string would be 
PSCRIPT. 

PDRIVDATA pdriv Pointer to driver data returned 

from the DevPostDevice modes 
function. 


PSZ pszLogAddr ess 


PSZ pszDriverName 
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PSZ pszDataType Pointer to a null-terminated 

string containing the format that 
data is to be queued in. 
PM_Q_STD allows the output 
to be metafiled; PM_Q_RAW 
leaves all data in device format. 

For info device contexts, the remainder of the fields can be ignored by setting the 
ICount paramter passed to the DevOpenDC function to 4. If the DC is successfully cre¬ 
ated, a presentation space can be created and associated with it. The presentation space 
should be created with device-independent coordinates such as PU_LOMETRIC or PU_TWIPS. 
The presentation space for the client window should be created using the same coordi¬ 
nate system as the print info DC. This allows the same coordinates to be used when draw¬ 
ing to the PS for the client window or the PS for the printer. In the PRNT sample, I 
chose to use LOMETRIC. The following code clip creates an info device context and an 
associated presentation space using the LO_ENGLISH coordinate system. 

DevOpenData.pszLogAddress = pPrd3->pszLogAddr; 

DevOpenData.pszDriverName = szDriverName; 

DevOpenData.pdriv = pDD; 

DevOpenData.pszDataType = "PM_Q_STD"; 

if (pDI->hlnfoDC = DevOpenDC (hab,0D_INF0,"*",4, 

(PVOID)&DevOpenData,0)) 

{ 

sizel.cx = 0; 
sizel.cy = 0; 

if(!(pDI->hlnfoPS = GpiCreatePS (hab,pDI->hInfoDC,&sizel 3 
GPIA_ASSOC | GPITJ/IICRO | PU_LOMETRIC)) ) 

{ 

DevCloseDC(pDI->hlnfoDC); 
pDI->hlnfoDC = 0; 

} 

else 

get_page_metrics(pDI); 

} 

Notice that the sizel parameter has both cx and cy parameters set to 0. This en¬ 
sures that maximum page size is created. If the info DC is successfully created, the 
GpiQueryPS function can be called to determine the size of the created PS. 

GpiQueryPS(pDI->hInfoPS,(PSIZEL)&pDI->PageSizel); 

In the sample print application, when a print object is selected in the Queue and Printer 
details dialog box, an information device context is created. The info DC is then passed 
to the DevQueryCaps function to determine device capablilites and sizes. Some of the 
values that relate to printing are displayed within the device capabilities group box. In¬ 
cluded here are the width and height of the print media in pels and device support for 
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functions such as GpiBitBlt and GpiSetPel. The queue and printer details dialog is 
shown in Figure 11.1. 


Figure ILL 
Queue And Printer 
Details dialog. 
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Job Properties... 


Update 


Querying Device Forms 

Many printers can be configured with multiple paper sources or bins. This allows print 
jobs to be printed on the desired paper sizes without waiting for the desired paper size to 
be added. Your application may determine the forms available on a print device by call¬ 
ing DevQueryHardcopyCaps. This function returns an array of HCINF0 structures, one 
for each form type. In the HCINF0 structure are the form name, sizes, and attributes. The 
attribute field indicates if the form is the current default form for the device 
(HCAPS_CURRENT) or if the form may be selected (HCAPS_SELECTABLE). If neither bit is 
set, the form is not installed on the device and should not be used. A form that is select¬ 
able may be specified by setting the form name in the spooler parameters of the 
DEV0PENSTRUC passed to DevOpenDC. The form name should follow the FORM = string. 
The form name should be taken from the szFormname field in the HCINF0 structure (for 
example: F0RM=LETTER). 

The Queue and Printer details dialog demonstrates enumerating the forms using the 
DevQueryHardcopyCaps function. Wh.en a print object is selected, the forms are que¬ 
ried and added to the forms list box. Below the list box is the form width and height as 
returned from the device in millimeters. The attribute flags are displayed along with the 
offsets of the clipping limits of the page. Notice that many of the forms enumerated from 
a device have no attribute bits set and are not selectable. If a form is specified that is not 
currently installed in the printer, the job is held until that form is available. 
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Determining Page and Printable Area Size 

Most print devices are unable to print on all portions of the physical page. The portion 
that can be drawn on by the printer is referred to as the printable area. This printable 
area size may be retrieved by calling the GpiQueryPS function after creating a device 
context. Be sure that the initial width and height used when creating the presentation 
space are set to 0. This ensures that the maximum presentation page is created. 

The physical page size may be determined by using the width and height values from 
the HCINFO structure for the selected form, cx and cy need to be converted from milli¬ 
meters to pels. This can be done by multiplying by the device resolution, which is in pels 
per meter, and dividing by 1,000 (the number of millimeters in a meter). Device resolu¬ 
tion for the X- and Y-axis can be retrieved by calling the DevQueryCaps function and 
requesting CAPS_HORIZONTAL_RESOLUTION and CAPS_VERTICAL_RESOLUTION. Once the 
page size is calculated, the device points are converted into world coordinate space. For 
example, take a look at the following code clip: 

DevQueryCaps (pDI->hlnfoDC,CAPS_HORIZONTAL_RESOLUTION,1L, 

(PLONG) &PtlRes.x); 

DevQueryCaps (pDI->hlnfoDC,CAPS_VERTICAL_RESOLUTION,1L, 

(PLONG) &PtlRes.y); 

pDI->PhyPageSizel.cx = (PtlRes.x * pHCInfo[i].cx) / 1000; 
pDI->PhyPageSizel.cy = (PtlRes.y * pHCInfofi].cy) / 1000; 

GpiConvert(pDI->hlnfoPS,CVTC_DEVICE,CVTC_WORLD,1,(PPOINTL)&pDI- 
>PhyPageSizel); 

There are two problems with the cx and cy fields of the HCINFO structure. While 
browsing the forms enumerated from the installed devices, you may have noticed the first 
one. The same form may have a different width and height based on the device driver 
that is selected. For example, the letter paper size may be reported to be 215 millimeters 
wide by one device and 216 by another. This occurs because different printer drivers are 
reporting different widths and heights for the same form size. The second problem is 
inherent in the use of millimeters as the unit of measurement. Millimeters do not pro¬ 
vide a fine enough resolution to accurately define the page size of high resolution devices 
such as laser printers. Rounding may cause page size calculation to be in error. 

Calculating Printer Offset 

Printer offset is the difference between the origin of the physical page and the origin of 
the printable area. Using the physical page size, printable area, and printer offset, an ac¬ 
curate representation of the page may be drawn in the application. The printer offset may 
be calculated by converting xLeftClip and yBottomClip fields of the HCINFO structure 
to pels: 
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pDI->PrintOffsetSizel.cx = (PtlRes.x * pHCInfo[i].xLeftClip) / 1000; 
pDI->PrintOffsetSizel.cy = (PtlRes.y * pHCInfo[i].yBottomClip) / 1000; 
/* Convert from device to world coordinate space */ 

GpiConvert(pDI->hInfoPS,CVTC_DEVICE,CVTC_WORLD, 1 ,(PPOINTL)&pDI- 
>PrintOffsetSizel); 

Some PM devices report a printer offset of 0; however, the presentation page size is 
not equal to the physical page size. It is also possible that the device will not return form 
information at all. If either of these situations occurs, an application can approximate the 
value by subtracting the printable area from the physical page size and dividing by two. 
Although not exact, this should be adequate for most needs. The physical page size may 
be retrieved by calling the DevQueryCaps function requesting the CAPS_WIDTH and 
CAPSJHEIGHT values: 

DevQueryCaps (pDI->hInfoDC 3 CAPS_WIDTH 3 1L,(PL0NG)&Ptl.x); 

DevQueryCaps (pDI->hInfoDC,CAPSJHEIGHT,1L,(PL0NG)&Ptl.y); 

GpiConvert (pDI ->hInfoPS,CVTC_DEVICE,CVTC_WORLDj1,&Ptl); 

pDI->Print0ffsetSizel.cx = (pDI->PhyPageSizel.cx - Ptl.x) / 2L; 

pDI->Print0ffsetSizel.cy = (pDI->PhyPageSizel.cy - Ptl.y) / 2L; 

Basic Printing 

Now that you can enumerate the installed print objects, create information device con¬ 
texts, and query the device capabilities, you can look at the print process. Sending output 
to the printer is not much different from sending output to the screen. The same func¬ 
tions used to create figures and text on-screen are used when printing. The big difference 
is that the presentation space being drawn into is associated with a print device con¬ 
text (DC) in place of a window DC. Therefore, the first step in printing is to create an 
0D_QUEUED or 0D_DIRECT device context. 

Queued device contexts cause printed output to be queued on a spooler queue. Once 
added to the queue, the job can be held, deleted, or repeated, independent of the appli¬ 
cation. It is recommended that all PM applications create queued device contexts. Direct 
printing causes the spooler to be bypassed, causing the printing application to wait until 
the print job is complete (assuming that the printing was not done in a separate thread). 
Direct printing should be avoided unless security of the printed output must be main¬ 
tained and access to spooler files and print objects cannot be limited. Spooled files are 
written to disk while waiting to be sent to the printer, and they may be copied if access to 
the spool directory is not limited. The spooler directory is specified on the spool path 
page of the spooler settings object. The default location for this object is in the system 
setup folder. If direct printing is required, a dedicated printer or output device should be 
used. Even with a dedicated device, it is possible for two jobs sent directly to the device 
to become intermixed. 
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Creating a print DC is very much like creating the information DC. In place of the 
OD_INFO type, the 0D_QUEUED flags should be used. As with the info DC, the first four 
parameters of DEVOPENSTRUCT must be initialized at a minimum. Later in this chapter, 
I’ll be using some of the other parameters, so I’ll discuss them now. The fields of the 
DEVOPENSTRUC as they apply to creating DCs of type 0D_QUEUED are as follows: 


TPSZ 

pszLogAddress 

Pointer to a null-terminated 
string that is the queue name 
from the pszName field of the 
PRQINF03 structure. Note 
that unlike the DCs of type 
OD_INFO, this is not the 
port name. 

PSZ 

pszDriverName 

Pointer to a null-terminated 
string that contains the device 
driver name. This should be the 
portion that precedes the period 
in the string pointed to by the 
pszDriverName parameter in the 
PRQINF03 structure. Using the 
example from above: 

PSCRIPT.HP LaserJet IHSi 

PS v52_3- The supplied 
string would be PSCRIPT. 

PDRIVDATA 

pdriv 

Pointer to driver data returned 
from the DevPostDevice modes 
function. 

PSZ 

pszDataType 

Pointer to a null-terminated 
string containing the format 
that data is to be queued in. 
PM_Q_STD allows the output 
to be metafiled; PM_Q_RAW 
leaves all data in device format. 

PSZ 

pszComment 

Pointer to a null-terminated 
string containing the document 
name that is used to describe this 
job once in the queue. 
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PSZ pszQueueProcName Pointer to a null-terminated 

string containing the name of the 
queue processor to be used for 
this job. If this parameter is 
NULL, the default queue 
processor PMPRINT is used. 

You may recall that PMPLOT 
may be optionally installed to clip 
output intended for a plotter. 

The default queue processor for 
the device is defined in the 
pszPrProc field of the 
PRQINF03 structure. 

PSZ pszQueueProcParams Pointer to a null-terminated 

string containing queue processor 
parameters. This field may be 
NULL. 

PSZ pszSpoolerParams Pointer to a null-terminated 

string containing spooler 
parameters. You may currently 
set the job priority and form used 
in the spooler parameters. If both 
are used, they should be separated 
by spaces: 

FORM=<formname>. 

Where formname is taken 
from the szFormname field 
of the HCINFO structure, 
if the form desired is not the 
current form or selectable, 
the job never prints. 
PRTY=<prority>. 

Where priority is a number 
ranging from 1 to 99, with 99 as 
the high. The default is 30 if no 
priority is specified. If the field is 
NULL, the job is printed on the 
current form using the default 
priority. 
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PSZ pszNetworkParams Pointer to a null-terminated 

string containing network 
parameters. This field is optional 
and may be NULL. 

Once the print device context is created, the print job begins when the 
DEVESC_STARTDOC escape is sent to the printer. Escapes are commands your application 
sends to the printer to direct it to perform an action or return some information. The 
STARTDOC escape tells the printer that a new print job is starting and all subsequent out¬ 
put is part of the same job until the job is ended. A pointer to a string that specifies the 
document name may be passed in the input parameter of the DevEscape function. If a 
string is specified, it becomes the job name (even if a name is supplied in the pszComment 
field of the DEVOPENSTRUC). If no input is supplied, pszComment is used if not NULL; 
otherwise the job name is blank. 

The presentation space must be associated with the DC prior to the STARTDOC es¬ 
cape. This may be done by creating the PS using the GPI_ASS0C flag or associating an 
existing PS with the print DC using the GpiAssociate function. After the PS is associ¬ 
ated with the print DC, the STARTDOC escape should then be sent to the printer. Using 
the presentation space handle in any function prior to the STARTDOC is invalid. This in¬ 
cludes attribute setting functions such as GpiSetAtt rs, as well as the drawing primitives. 

Once the print job is started, all GPI drawing is output to the printer. When a page 
is completed and another page exists, the DEVESC_NEWFRAME escape should be sent. This 
causes the printer to perform a page eject. If the job must be ended before it has com¬ 
pleted, the DEVESC_ABORTDOC escape causes any output from the current job waiting to 
be sent to the printer to be cleared, and the job ends. This escape is typically used to 
implement a print cancel feature in an application. When the print job is complete, it is 
ended by sending the DEVESC_ENDDOC escape to the printer. The return parameter from 
the DevEscape function contains the job ID that can be used to track the progress of 
the print job in the queue if desired. If the DEVESC_ABORTDOC escape is used to cancel a 
print job, it is unnecessary to send the DEVESC_ENDDOC escape. The flow diagram in Fig¬ 
ure 11.2 depicts the various steps of the printing process. 

Printing in an Application 

With all the basics in place, I can define the requirements for a simple print application 
called PRNT.EXE. PRNT allows the current application printer to be selected from a 
list of installed devices. Part of the selection process includes displaying the Job Proper¬ 
ties dialog upon request. It must also display a representation of the print page and print¬ 
able area in the client window. PRNT should have a print menu item that, when selected, 
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posts a dialog to verify the requested print operation. If the print is confirmed, the print 
dialog is dismissed and a print status dialog is displayed during the duration of the print 
job. This dialog contains a cancel button that can abort the selected print job. 


Figure 11.2. 

The printing flowchart. 
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In order to manage all of the information about print devices, I will define the 
DEVICEINFO structure. Print DCs, physical and printable sizes, along with the point¬ 
ers to driver data and form information are maintained in this structure. The application 
maintains one global variable of this type called CurrentDI. The information on the 
currently selected application printer is stored in this variable. 

When the application starts, it calls the init_app function, which determines the 
default print device that becomes the current application default device. It then queries 
the current driver data from that device and creates an information DC used to draw a 
representation of the page in the client window (see Figure 11.3). 


Figure 11.3. 

PRNT application page 
representation. 



Up to this point, all drawing has been done in device units. This worked fine for 
drawing thermometers in control windows. However, because of the variation in resolu¬ 
tion between the display and printer, a device-independent coordinate space must be used. 
A PS for the client area is created using the PU_LOMETRIC mapping mode. The mode was 
chosen arbitrarily from the defined coordinate spaces and could have been PU_TWIPS or 
PU_LOENGLISH. In order for the page to be entirely visible in the maximized client win¬ 
dow, the viewing matrix is scaled to reduce page size by 50 percent. When the client 
window is drawn, the current print page is represented by a white rectangle with a black 
border. The printable area on the page is shown using a blue dashed line. 

The PRNT application contains a Print Selection dialog box. This dialog contains a 
list box that is filled with the installed print objects during the processing of the WM_I NITDLG 
message. The Print Selection dialog box is shown in Figure 11.4. 
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Figure 11.4. 

Print object selection 



After adding all objects, the application default printer is selected. The dialog also 
has a Job Properties pushbutton, which, when pushed, posts the printers Job Properties 
dialog. The first time this dialog is displayed, the job properties for all devices will be 
their system default values. The Job Properties dialog for the postscript printer is shown 
in Figure 11.5. 


Figure 11.5 . 

The PostScript Job 
Properties dialog box. 
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Changes made to the job properties of the selected device should be maintained by 
the application. For example, if the user posts the Job Properties dialog and changes the 
page orientation from portrait to landscape, the next time that the Job Properties dialog 
is posted, landscape should still be selected. In order to maintain job properties of a printer, 
the driver data returned from the DevPostDeviceModes function must be saved. When 
the dialog box is dismissed by selecting the OK button, the selected device becomes the 
application default, and contents of the Current DI structure are updated accordingly. If 
Cancel is selected, the application default printer remains unchanged. 

When the Print menu item is selected, a print confirmation dialog is displayed. This 
dialog displays the name of the target printer and the document name. You may change 
the number of copies and priority of the print job through two spinner controls in the 
dialog. These selections are passed to the DevOpenDC function as queue processor and 
spooler parameters, respectively. If the OK button is selected, the values set in the copies 
and priority controls are retrieved, the dialog is closed, and the print status dialog is 
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created. If Cancel is selected, the dialog is closed with no further action. Figure 11.6 shows 
the print confirmation dialog 


Figure 11.6. 

Print confirmation 
dialog. 



The print status dialog starts the print job, displays the status of that job, and allows 
the job to be canceled. When it receives the WM_INITDLG message, it initializes the printer 
and job name fields. It then sets the status field to “Initializing Printer” and posts a user 
defined WM_START_PRINT message to the client window. When the client window re¬ 
ceives this message, it calls the process_print function. You may be wondering why 
process_print was not called directly from the dialog. Although this could have been 
done, you want that dialog to report only the status of the job, not to actually do the 
printing. The process_print function is responsible for creating the print device con¬ 
text and sending output to the printer. It first makes a copy of the data in the Cu rrentDI, 
which is passed into the create_print_DC function. This allows the function to be re¬ 
entrant when a printing thread is added in Chapter 12, “Threads and Semaphores.” If 
the DC is successfully created, a WM_PRINT_STATUS message is posted to the status dia¬ 
log, which updates the status text accordingly. 

When the job is completed, the DEVESC_ENDDOC escape is sent to the printer, and a 
status message indicating job completion is posted to the dialog. The print DC and PS 
are then destroyed, and the copy of the CurrentDI structure is freed. In nonthreaded 
print processing, the print status dialog is application modal; in the threaded version, it 
is not. 

Tracking Your Print Job Using the Spooler API 

Once your print job is in the queue, you can use the spooler API to track the status of 
submitted jobs in your application. You can also hold, delete, or copy the job. You could 
also write a single application that manages all queues and their jobs. Note that these 
functions will not work if the user disables the spooler. An application cannot change the 
status of the spooler; however, the spooler status may be retrieved by querying the QUEUE 
section of the PM_SPOOLER section in the system INI file. If the spooler is enabled, the 
data field is 1; otherwise, it is 0. Let’s look at the spooler functions that manipulate 
print jobs. 
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SplControlDevice 

This function enables you to control a print device. It may be paused or continued, and 
the current print job may also be restarted or deleted. 

SplCopyJob 

This function copies a job within a given print queue. Jobs may not be copied to another 
print queue. However, this restriction may be lifted in the future. 

SplDeleteJob 

This function deletes a specific job ID 
from the DEVESC_ENDDOC escape. Job 
function. 

SplEnumJob 

This function can return an array of job IDs in the queue or an array of PRJINF02 struc¬ 
tures containing the status of each print job in the queue. The PRJINF02 structure 
contains the job ID, priority, status, size, document name, title, and user name. The job 
status indicates whether the job is being held or whether an error occurs during pro¬ 
cessing. 

An application that tracks the print job for the user can report out-of-paper errors or 
indicate whether the device is waiting for a form change. 

SplHoldJob 

This function holds a specific job in a given queue. A job may be held if it has not started 
printing. The job may be restarted with the SplReleaseJob function. 

SplHoldQueue 

This function changes the status of a print queue from released to held. All jobs in the 
queue awaiting the print device are held regardless of their individual status. The status 
of jobs currently printing is unaffected. The queue may be released using the 
SplReleaseQueue function. 

SplPurgeQueue 

This function removes all jobs in the queue awaiting the print device. Currently printing 
jobs are not affected. 


from a given print queue. The job ID is returned 
IDs may also be retrieved from the SplEnumJob 
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SplQueryJob 

This function queries information about a specific print job in a queue. A PRJINF02 or 
PRJINF03 structure is returned based on the requested information level. The PRJINF02 
structure contains the job ID, priority, status, size, document name, title, and user name. 
The PRJ INF03 structure contains that information along with more details, such as queue 
processor parameters and status string. The printer name, driver name, and data are also 
available. 

SplReleaseJob 

This function changes the status of a specific print job in the queue from held to released. 
The job is not sent to the printer if the queue is currently held. 

SplReleaseQueue 

This function changes the status of a print queue from held to released. Jobs in the queue 
that are not held are printed, provided that the requested form and other job-specific 
criteria are met by the print device or devices. 

SplSetJob 

This function modifies one or all parameters of a job, such as the number of copies 
or priority. 

Installing Private Device Drivers 

The spooler API provides the SplCreateDevice and SplCreateQueue functions to be 
used to add a new print object to the desktop. However, if your application requires a 
private device driver, you may add an entry to the PM_DEVICE_DRIVERS application sec¬ 
tion of the user system INI file. The section name should be the physical name of the 
installed driver. For example, if the name of the driver module was MYDRIVER.DRV, 
the section name would be MYDRIVER. The data for that section is the full path and filename 
of the device. Once installed, you may create a device context with that driver using the 
DevOpenDC function. 

Converting Profile Queries 
to the Spooler Equivalents 

This section is designed to assist you in converting code originally written for 1 .x to 2.1. 
The INI file entries containing information on installed and default printers are listed. If 
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you are developing new code, use the spooler API and ignore most of this section. You 
may find it helpful to use the INITOR program from Chapter 8, “Profile Management,” 
and to browse through the entries as they are discussed. However, you should not de¬ 
pend on these entries for future versions of OS/2. 

PM_SPOOLER 

QUEUE 

This entry contains the physical name of the default queue. The physical name may be 
found on the view page of a print object’s settings notebook. If you have more than one 
printer installed on your machine, you may change this value by selecting the Set De¬ 
fault menu item of any print object. 


Replacement Spooler API 

Determining the default print object is unfortunately the one hole in the spooler API. As 
a result, the profile function Prf Query Prof ile string must still be used to determine 
the system default printer. The SplQueryQueue may then be used to retrieve the queue 
description and other details in the PRQINF03 structure. The string returned ends in a 
semicolon, which should be removed before passing the name to the SplQueryQueue 
function. Selecting the default print object is not required. You can maintain an applica¬ 
tion default printer by writing the last selected device as private entries in an INI file. On 
program start-up, the entry can be read and the application default selected from the print 
objects returned from the SplEnumQueue function. 

PRINTER 

In releases of OS/2 prior to 2.1, this contained the default printer. In 2.1, it remains for 
compatibility with 1.x applications and contains the same value as the QUEUE keyname 
described above. 


Replacement Spooler API 

No spooler API exists to retrieve this value. 


PM_SPOOLER_PRINTER 

This application section contains entries for installed printer drivers. The keyname is the 
physical device name, and the data string is defined as follows: 
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<addr>;<ddl>;<ql>;<netopt>;<timeout>; 

ex. LPT 1 ; PSCRIPT.HP LaserJet IHSi PS v52_3;HPLaserJ ; ;45; 


<addr> 


<ddl> 


<ql> 


<netopt> 

<timeout> 


The physical hardware address 
(for example, LPTn, COMn, 
IEEEn) to which the device is 
connected. 

A list of device drivers defined for 
the printer (note the comma 
between each name), which can 
be NULL. The first one is taken 
as the default. The driver name is 
in the form <printer driver 
name>. <hardware description>. 

A list of queues defined for the 
printer; this contains the physical 
name of the queue the driver is 
associated with. 

The network printer options, 
which may be omitted. 

The timeout value in seconds. 


Replacement Spooler API 

This information may now be retrieved from the SplEnumQueue function. 

PM_SPOOLER_PRINTER_DESCR 

<printer name> 

This entry contains the user-supplied printer description. Once again, this field remains 
for compatibility with 1.x applications. When a print object is installed, this entry 
contains the initial queue description, which may also be found in the 
PM_SPOOLER_QUEUE_DESC. This string may be found in the title entry on the general page 
of the printer settings notebook, and it appears as the icon text of a print object. This 
entry will never be updated as the user changes the print object description. 


Replacement Spooler API 

The pszComment field of the PRQINF03/PRQINF06 structure now contains the current 
queue description. This structure may be retrieved by calling SplEnumQueue or 
SplQueryDevice. 
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PM_SPOOLER_QUEUE_DESCR 

<queue name> 

This entry contained the user-supplied queue description. This value is the descriptive 
name given by the user that appears as the icon window text in the title entry on the general 
page of printer settings. Unlike PM_SPOOLER_PRINTER_DESCR, this field is updated when 
the queue name changes. 

Replacement Spooler API 

The pszComment field of the PRQINF03/PRQINF06 structure now contains the current 
queue description. This structure may be retrieved by calling SplEnumQueue or 
SplQueryDevice (see Figure 11.7). 

Figure 11.7. 

Relationship of the 
PRQINF03, 

DEVOPENSTRUC, 

and PRDINF03 PRQINF03 PRDINF03 
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The PRNT Application 

I have provided a fairly sophisticated little print application to illustrate these concepts. 
In order to use it, of course, you need an actual printer installed on your system. The 
following files are needed to build the PRNT application. 

ABOUT.DLG 

PRNT.DLG 

DIALOG.H 

PRNT.C 

PRNTINFO.C 

PRNT.DEF 

PRNT.H 

PRNT.ICO 

PRNT.MAP 

PRNT.RC 


PRNT.DLG 


/* 


Print Dialogs 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGINCLUDE 1 "DIALOG.H" 

DLGTEMPLATE SELECT_PRINTER_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Select Printer", SELECT_PRINTER_DLG, 65, 89, 253, 69, 
WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 


LISTBOX 

DID_QUE U E_NAM E S, 5, 

CO 

CV1 

241 , 

40 

DEFPUSHBUTTON 

"-Ok", DID_OK, 4, 3, 

40, 

14 


PUSHBUTTON 

“Cancel", DID_CANCEL 

CD 

LO 

, 3, 

40, 

PUSHBUTTON 

“Job Properties...“, 

DID 

_J0BPR0PS 


14 

END 

END 

DLGTEMPLATE PRINT_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Print", PRINT_DLG, 72, 106, 250, 66, WS_VISIBLE, 
FCF_SYSMENU | 

FCF TITLEBAR 


; 
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PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 


BEGIN 

LTEXT 

ENTRYFIELD 

LTEXT 

ENTRYFIELD 

LTEXT 

CONTROL 


"Printer:", -1, 7, 52, 37, 8 

11 ", DID_PRINTER, 48, 54, 196, 8, ESJ/1ARGIN 

"Document:", 106, 6, 37, 49, 8 

"", DID_DOCUMENT, 48, 39, 195, 8, ESJVIARGIN 

"Copies:", -1, 7, 24, 33, 8 

"", DID_COPIES, 47, 24, 30, 12, WC_SPINBUTTON, 
SPBS_ALLCHARACTERS | SPBS_MASTER | SPBS_SERVANT 


LTEXT 

CONTROL 

WC_SPINBUTTON, 


WS_VISIBLE 

DEFPUSHBUTTON 

PUSHBUTTON 

END 

END 


SPBS_JUSTDEFAULT | SPBS_FASTSPIN | WS_GROUP ] 
WS_TABSTOP | WS_VISIBLE 
"Priority:", -1, 89, 24, 27, 8 
"", DID_PRIORITY, 120, 24, 52, 12, 

SPBS_ALLCHARACTERS | SPBS_READONLY | SPBS_MASTER 

SPBS_SERVANT j SPBS_JUSTDEFAULT | SPBS_JUSTLEFT 

SPBS_FASTSPIN j WS_GROUP | WS_TABSTOP | 

"Ok", DID_OK, 14, 4, 40, 14 
"Cancel", DID_CANCEL, 63, 4, 40, 14 


DLGTEMPLATE PRINT_STATUS_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Print Status", PRINT_STATUS_DLG, 94, 153, 240, 61, 
WS_VISIBLE, 


FCF_SYSMENU j FCF_TITLEBAR 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv 


BEGIN 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

PUSHBUTTON 

DEFPUSHBUTTON 


"Job:", -1,5, 48, 31, 8 
"", DID_JOBNAME, 42, 48, 184, 8 
"Printer:", -1, 5, 36, 31, 8 
"", DID_PRINTER, 42, 37, 184, 8 
"Status:", -1, 5, 24, 31, 8 
"", DID_STATUS, 42, 25, 184, 8 
"Cancel", DID_CANCEL, 92, 4, 40, 
"Ok", DID_0K, 91, 4, 40, 14 


END 


14 


END 


DLGTEMPLATE QUEUE_INFO_DLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Queue And Printer Details", QUEUE_INFO_DLG, 25, 42, 378, 
160, WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 
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BEGIN 

LISTBOX 

LTEXT 

GROUPBOX 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LISTBOX 

LTEXT 

GROUPBOX 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

GROUPBOX 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 

LTEXT 


DID_QUEUE_NAMES, 6, 117, 181, 36 
"Queue Description", -1, 8, 151, 90, 8 
"Queue", SELECT_PRINTER_DLG, 6, 55, 182, 59 
"Queue Name:", -1, 11, 98, 45, 8 
"", DID_QUEUE_NAME, 61, 98, 111, 8 
"Default Device:", -1, 11, 88, 50, 8 
"", DID_DEFAULT_DEVICE, 61, 88, 121, 8 
"Print Devices:", -1, 11, 78, 48, 8 
"", DID_PRINTERS, 61, 78, 121, 8 
"Priority:", -1, 11, 68, 26, 8 
"", DID_PRIORITY, 38, 68, 24, 8 
"Status:", -1, 70, 68, 25, 8 
"", DID_STATUS, 98, 68, 30, 8 
"Start Time:", -1, 11, 58, 39, 8 
"", DID_START_TIME, 52, 58, 29, 8 
"End Time:", -1, 98, 58, 38, 8 


"", DID_ 

END TIME 

, 142 

, 58. 

, 32, 

, 8 

"Jobs:", 

’ -1 , 138 

CO 

CO 

<s> 

CM 

8 


"", DID_ 

_NUMBER_JOBS, 

162, 

CO 

CO 

20 

DID_FORMS, 197, 

117, 

173, 

34 


"Forms", 

, -1, 198 

, 151 

, 27: 

, 8 



"Form Information", -1, 196, 55, 175, 59 
"Width in MM:", -1, 204, 96, 44, 8 


"", DID_FORM_CX, 

257, 

CO 

CD 

18, 

8 

"Height in MM:", 

-1, 

285, 

96, 

47 

"", DID FORM CY, 

338, 

CO 

05 

18, 

8 

"Left Clip:", -1 

, 204 

CO 

, 29, 

, 8 


"", DID_LEFT_CLIP, 241, 76, 20, 8 
"Bottom Clip:", -1, 273, 76, 38, 8 
"", DID_BOTTOM_CLIP, 320, 76, 20, 8 
"Attribute:", PRINT_STATUS_DLG, 204, 86, 30, 8 
, DID_FORM_ATTR, 238, 86, 87, 8 
"Right Clip:", -1, 204, 66, 32, 8 
"", DID_RIGHT_CLIP, 241, 66, 20, 8 
"Top Clip:", -1, 272, 66, 37, 8 
"", DID_TOP_CLIP, 320, 66, 20, 8 
"Device Capabilites", -1, 5, 22, 367, 30 
"Technology:", -1, 11, 35, 40, 8 
"", DID_TECHNOLOGY, 51, 35, 72, 8 
"Width in Pels:", -1, 126, 35, 43, 8 
"", DID_CAPS_WIDTH, 170, 35, 19, 8 
"Height in Pels:", PRINT_DLG, 194, 35, 47, 8 
"", DID_CAPS_HEIGHT, 239, 35, 20, 8 
"Horiz Res:", 106, 260, 35, 33, 8 
"", DID_HORZ_RES, 293, 35, 20, 8 
"Vert Res:", -1, 316, 35, 30, 8 
"", DID_VERT_RES, 348, 35, 20, 8 
"GpiBitBlt:", -1, 11, 25, 32, 8 
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LTEXT 

11 ", DID_BITBLT, 44, 

25, 

20, 

8 


LTEXT 

"Banding:", -1, 67, 

25, 

31, 

8 


LTEXT 

DID_BANDING, 97, 

25, 

20, 

8 


LTEXT 

"GpiSetPel:", -1, 123, 25, 35, 8 


LTEXT 

DID_SETPEL, 158, 

25, 

20, 

8 


LTEXT 

"Raster Fonts:", -1, 

184 

25 

44, 

8 

LTEXT 

"", DID_RASTER_FONT, 

228 

25 

20, 

8 

LTEXT 

"Kerning:", -1, 256, 

25, 

29, 

8 


LTEXT 

DID_KERNING, 286 

, 25 

20 

8 


LTEXT 

"Palette:", -1, 318, 

25, 

28, 

8 


LTEXT 

"", DID_PALETTE, 347 

, 25 

20 

8 


DEFPUSHBUTTON 

"Ok", DID_0K, 6, 3, 

40, 

14 



PUSHBUTTON 

"Cancel", DID_CANCEL 

, 55 

, 3, 

40, 

14 

PUSHBUTTON 

"Job Properties...", 
14 

"Update", DID_UPDATE 

DID 

_JOBPROPS 

, 106 

PUSHBUTTON 

, 184, 3 

40, 

14 


END 

END 


DIALOG.H 


/* 


Print Dialog Header File 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define QUEUE_INFO_DLG 100 
#define SELECT_PRINTER_DLG 102 
#define PRINT_DLG 103 
#define PRINT_STATUS_DLG 104 
#define STATUS JVND 105 
#define DID_QUEUE_NAMES 200 
#define DID_PRIORITY 201 
#define DID_STATUS 202 
#define DID_NUMBER_JOBS 203 
#define DID_START_TIME 204 
#define DID_END_TIME 205 
#define DID_DEFAULT_DEVICE 206 
#define DID_PRINTERS 207 
#define DID_TECHNOLOGY 208 
#define DID_FORMS 209 
#define DID_FORM_CX 210 
#define DID_FORM_CY 211 
#define DID_LEFT_CLIP 212 
#define DID BOTTOM CLIP 214 
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OS/2 
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#define DID_FORM_ATTR 215 
#define DID_RIGHT_CLIP 216 
#define DID_TOP_CLIP 217 
#define DID_CAPS_WIDTH 218 
#define DID_CAPS_HEIGHT 219 
#define DID_HORZ_RES 220 
#define DID_VERT_RES 221 
#define DID_BITBLT 222 
#define DID_BANDING 223 
#define DID_SETPEL 224 
#define DID_RASTER_FONT 225 
#define DID_KERNING 226 
#define DID_PALETTE 227 
#define DID_JOBPROPS 228 
#define DID_UPDATE 229 
#define DID_PRINTER 300 
#define DID_DOCUMENT 301 
#define DID_COPIES 302 
#define DID_JOB_LIST 400 
#define DID_JOBNAME 401 
#define DID QUEUE NAME 240 


PRNT.C 


/* 


Printing Sample Program 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_WIN 
#define INCL_GPI 
#define INCL_DEV 
#define INCL_SPL 
#define INCL_SPLDOSPRINT 
#define INCL_WINERRORS 
#define INCL_DOSPROCESS 
#include <os2.h> 

#include <string.h> 

#include <stdio.h> 

#include "prnt.h" 

#include "dialog.h" 

#include "..\common\about.h" 


#define NERR BuffTooSmall 2123 
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MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY PrintlnfoDlgProc (HWND, ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY PrintStatusProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY PrintDlgProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY SelectPrinterDlgProc (HWND,ULONG,MPARAM,MPARAM); 

HAB hab; 

HWND hWndFrame, 
hWndClient; 

HWND hHintWnd; 

HWND hMenu; 

CHAR szTitle[64]; 

CHAR szBuff1[MAX_BUFF]; 

CHAR szFontFace[] = "8.Helv"; 

CHAR szPM_Q_STD [ ] = 11 PM_Q_STD"; 

PVOID pMem; 

int nSysFontHeight; 

LONG IColorWorkSpace; 

USHORT usDraw = IDM_DISP_BLANK; 

CHAR szPriority[3][10] = 

{ 

"Low", 

"Standard", 

"High" 

}; 


LONG IPriority[3] = 

{ 

1,50,99 

}; 


/* Array of pointers to priority strings (for spinner control) */ 
PVOID pszPriorities[3] = 

{ 

&szPriority[0], 

&szPriority[1], 

&szPriority[2] 

}; 


DEVICEINFO CurrentDI; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR | FCF_SYSMENU ] 

FCF_SIZEBORDER | FCF_MINMAX | 
FCF_SHELLPOSITION \ FCF_TASKLIST | 
FCF_ICON | FCFJ/IENU; 
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CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, CS_SIZEREDRAW, 

0 ); 

WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

DosAllocMem((PPVOID)&pMem,0x1000,PAG_READ J PAG_WRITE); 

DosSubSet(pMem,DOSSUB_INIT | DOSSUB_SPARSE_OBJ,0x8000); 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

hMenu = WinWindowFromID (hWndFrame,FID_MENU); 
create_status_line(hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 

DosFreeMem(pMem); 
return (0); 


VOID APIENTRY center_window (HWND hWnd) 

{ 

ULONG ulScrWidth, ulScrHeight; 

RECTL Recti; 

ulScrWidth = WinQuerySysValue (HWND_DESKTOP, SV_CXSCREEN); 
ulScrHeight = WinQuerySysValue (HWND_DESKTOP, SV_CYSCREEN); 
WinQueryWindowRect (hWnd, &Rectl); 

WinSetWindowPos (hWnd, HWND_T0P, (ulScrWidth-Recti.xRight)/2, 
(ulScrHeight-Recti.yTop)/2, 0, 0, SWP_MOVE | SWP_ACTIVATE); 
return; 


BOOL APIENTRY create_info_DC(PPRQINF03 pPrq3,PDEVICEINFO pDI) 

/*.*\ 


This function will intialize the pDI DEVICEINFO structure based 
on the queue pointed to by pPrq3. If pDI contains an existing 
entry, its info DC is destroyed and any form info is freed. 
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A new info DC is created and the get_page_metrics function is used 
to initialize size information in the stucture. 


\*....*/ 

{ 

PDRIVDATA pDD; 

PPRDINF03 pPrd3; 

DEVOPENSTRUC DevOpenData; 

SIZEL sizel; 

ULONG ulNeeded = 0; 

int i; 

CHAR szDriverName[MAX_DEVICENAME]; 

CHAR szDeviceName[MAX_DEVICENAME]; 


/* Free existing info DCs and PSs */ 
if (pDI->hlnfoPS) 

{ 

GpiAssociate(pDI->hlnfoPS,0); 

GpiDestroyPS(pDI->hInfoPS); 
pDI->hInfoPS = 0; 

DevCloseDC(pDI->hInfoDC); 
pDI->hlnfoDC = 0; 

} 

if (pDI->pHCInfo) 

{ 

DosSubFree(pMem,pDI->pHCInfo,(pDI->lSizeHC * sizeof(HCINFO))); 
pDI->pHCInfo = 0; 
pDI->lSizeHC = 0; 

} 

if ((i = strcspn(pPrq3->pszDriverName,".")) != 0 ) 

{ 

strncpy((PSZ)szDriverName,(PSZ)pPrq3->pszDriverName,i); 
szDriverNamefi] = '\0'; 

strcpy((PSZ)szDeviceName,(PSZ)&pPrq3->pszDriverName[i +1]); 

} 

if (SplQueryDevice(0,pPrq3->pszPrinters,3,0,0,&ulNeeded) != 
NERR_BuffTooSmall) 
return(FALSE); 

if (DosSubAlloc(pMem,(PPV0ID)&pPrd3,ulNeeded)) 
return (FALSE); 

if (SplQueryDevice(0,pPrq3->pszPrinters,3,(PVOID)pPrd3,ulNeeded, 
&ulNeeded) == 0) 

{ 

if (pDI->pDrivData) 
pDD = pDI->pDrivData; 
else 

pDD = pPrq3->pDriverData; 
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strcpy(pDI->szQueueDesc,pPrq3->pszComment); 
strcpy(pDI->szDriverName,pPrq3->pszDriverName); 
strcpy(pDI->szQueueName,pPrq3->pszName); 

DevOpenData.pszLogAddress = pPrd3->pszLogAddr; 
DevOpenData.pszDriverName = szDriverName; 
DevOpenData.pdriv = pDD; 

DevOpenData.pszDataType = (PSZ)szPM_Q_STD; 


if ((pDI->hInfoDC = DevOpenDC (hab,OD_INFO } "* M ,4, 

(PVOID)&DevOpenData,0)) != 0) 

{ 

sizel.cx = 0; 
sizel.cy = 0; 

if (!(pDI->hInfoPS = GpiCreatePS (hab,pDI->hlnfoDC,&sizel, 
GPIA_ASSOC | GPIT_MICRO | PU_LOMETRIC))) 

{ 

DevCloseDC(pDI->hInfoDC); 
pDI->hlnfoDC = 0; 

} 

else 

{ 

get_page_metrics(pDI); 

} 

} 

} 

else 

post_error(hWndClient,ID_ERR_FAIL_DEV_QUERY); 

DosSubFree(pMem,pPrd3,ulNeeded); 
return((BOOL)pDI->hInfoPS); 


BOOL APIENTRY create_print_DC(PDEVICEINFO pDI) 

/*.*\ 

This function will create an OD_QUEUED device context based on the 
contents of the pDI parameter. If successful, a presentation space 
is created and the DEVESC_STARTDOC escape is issued. The 
presentation space is then reset from indexed to RGB mode. 


\*.*/ 

{ 

DEVOPENSTRUC DevOpenStr; 

CHAR szQueueProcParams[9]; 

CHAR szSpoolerParams[9]; 

CHAR szDriverName[MAX_DEVICENAME]; 

int i; 
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memset((PVOID)&DevOpenStr 3 0 3 sizeof(DevOpenStr)); 

/* Set priority in spooler params */ 

sprintf ((PSZ)szSpoolerParams, (PSZ)" PRTY=%d", pDI ->lPriority) 

/* Set number of copies in the queue processor params */ 
sprintf((PSZ)szQueueProcParams,(PSZ)"C0P=%d",pDI->lCopies); 

WinLoadString(hab,0 3 IDS_JOB_TITLE 3 sizeof(szBuffl),szBuffl); 

if ((i = strcspn(pDI->szDriverName,".")) != 0) 

{ 

strncpy((PSZ)szDriverName,(PSZ)&pDI->szDriverName,i); 
szDriverName[i] = '\0'; 

} 

DevOpenStr.pszLogAddress 
DevOpenStr.pszDriverName 
DevOpenStr.pdriv 
DevOpenStr.pszDataType 
DevOpenStr.pszComment 
DevOpenStr.pszQueueProcParams = (PSZ)szQueueProcParams; 
DevOpenStr.pszSpoolerParams = (PSZ)szSpoolerParams; 

if ((pDI->hPrintDC = DevOpenDC(hab,OD_QUEUED,,9, 

(PVOID)&DevOpenStr,(HDC)0)) != 0 ) 

{ 

if (!(pDI->hPrintPS = GpiCreatePS(hab 3 pDI->hPrintDC,(PSIZEL) 
&pDI->PageSizel 3 PU_LOMETRIC | GPIA_ASSOC ))) 

{ 

DevCloseDC(pDI->hPrintDC ); 
pDI->hPrintDC = 0; 

} 

else 

{ 

DevEscape(pDI->hPrintDC 3 DEVESC_STARTDOC 3 strlen(szBuff1), 
szBuffl,0,0); 

GpiCreateLogColorTable (CurrentDI.hPrintPS,LCOL_RESET 3 
LCOLF_RGB 3 0 3 0 3 NULL); 

} 

} 

else 

WinGetLastError(hab); 
return((BOOL)pDI->hPrintPS); 


= pDI->szQueueName; 
= szDriverName; 

= pDI->pDrivData; 

= (PSZ)szPM_Q_STD; 

= (PSZ)szBuffl; 


void APIENTRY create_status_line(HWND hWndClient) 
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/*.-.*\ 

This function creates a static window positioned across the bottom 
of the client window which will display hint text when menus are 
browsed. 


\*.*/ 

{ 

FONTMETRICS fontMetrics; 

HPS hPS = WinGetPS(hWndClient); 

RECTL Recti; 

LONG IColor; 

WinQueryWindowRect(hWndClient,(PRECTL)&Rectl); 

GpiQueryFontMetrics(hPS,sizeof(FONTMETRICS), 

(PFONTMETRICS)&fontMetrics); 
nSysFontHeight = fontMetrics.IMaxBaselineExt + 4; 

WinSendMsg(hWndClient,WM_SIZE,0, 

MPFR0M2SH0RT(Recti.xRight,Recti.yTop)); 

hHintWnd = WinCreateWindow (hWndClient,WC_STATIC,"", 

WS_VISIBLE 1 SS_TEXT j DT_LEFT | DT_VCENTER , 

0,0,Recti.xRight,nSysFontHeight, 
hWndClient,HWND_T0P,1,NULL,NULL); 

IColor = CLR_PALEGRAY; 

WinSetPresParam(hHintWnd,PP_BACKGROUNDCOLORINDEX,sizeof(PLONG), 
&lColor); 

IColor = CLR_BLACK; 

WinSetPresParam(hHintWnd,PP_FOREGROUNDCOLORINDEX,sizeof(PLONG), 
&lColor); 

WinSetPresParam(hHintWnd,PP_FONTNAMESIZE,strlen(szFontFace)+1, 
(PVOID)szFontFace); 

WinReleasePS(hPS); 

} 


void APIENTRY display_hint(SHORT sMenuID) 

/*.*\ 


This function will load a menu hint string based on the supplied 
id and display that string in the status window. 



CHAR szBuff2[MAX_BUFF]; 


if (sMenuID == -1) 
szBuff2[0] = 1 \0‘ ; 
else 
{ 
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WinLoadString(hab,0,sMenuID,sizeof(szBuff2),szBuff2); 
if ( (sMenuID == IDM_PRINT) || (sMenuID == IDM_PRINT_THREAD) ) 
strcat(szBuff2,CurrentDI,szQueueDesc); 

} 

WinSetWindowText(hHintWnd , szBuff2); 


void APIENTRY draw_page(HPS hPS) 

/*.- .. *\ 

This function will draw a rectangle or ellipse scaled to the 
current printer page. 

\*. . */ 

{ 

AREABUNDLE ab; 

LINEBUNDLE lb; 

ARCPARAMS arcparms; 

POINTL ptl; 

switch (usDraw) 

{ 

case IDM_DISP_BLANK: 
break; 

case IDM_DISP_BOX: 
ab.lColor = RGB_RED; 

GpiSetAttrs (hPS,PRIM_AREA,ABB_COLOR,0,&ab); 
lb.IColor = RGB_GREEN; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs(hPS,PRIM_LINE,LBB_COLOR | LBB_TYPE,0,(PBUNDLE)&lb); 

ptl.x = ptl.y = 0; 

GpiMove(hPS,&ptl); 

ptl.x = CurrentDI.PageSizel.cx; 

ptl.y = CurrentDI.PageSizel.cy; 

GpiBox (hPS,DRO_OUTLINEFILL,&ptl,0,0); 
break; 

case IDM_DISP_ELLIPSE: 
ab.lColor = RGB_GREEN; 

GpiSetAttrs (hPS,PRIM_AREA,ABB_COLOR,0,&ab); 
lb.IColor = RGB_BLACK; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs(hPS,PRIM_LINE, LBB_C0L0R j LBB_TYPE,0,(PBUNDLE)&lb); 

/* define the bounding box for the arc */ 
arcparms.lP = CurrentDI.PageSizel.cx / 2L; 
arcparms.lQ = CurrentDI.PageSizel.cy / 2L; 
arcparms.lR = 0L; 
arcparms.lS = 0L; 

GpiSetArcParams(hPS, (PARCPARAMS)&arcparms); 
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/* Calculate the center point of bulb */ 
ptl.x = arcparms.lP; 
ptl.y = arcparms.lQ + 1; 

GpiMove (hPS,&ptl); 

GpiFullArc(hPS,DRO_OUTLINEFILL,MAKEFIXED(1,0)); 
break; 
default: 
break; 

} 

} 


void APIENTRY draw_page_background(HPS hPS) 

/*.*\ 


This function draws the "print page" in the client area. The 
physical page is drawn as a white rectangle with a black border 
and the printable area is drawn as a blue dashed outline. 


\*.*/ 

{ 

AREABUNDLE ab; 

LINEBUNDLE lb; 

POINTL ptl; 


/* Draw the physical page white with a black border */ 
ab.lColor = RGBJVHITE; 

GpiSetAttrs(hPS,PRIM_AREA,ABB_C0L0R,0,(PBUNDLE)&ab); 
lb.lColor = RGB_BLACK; 
lb.usType = LINETYPE_SOLID; 

GpiSetAttrs(hPS,PRIM_LINE,LBB_C0L0R | LBB_TYPE,0,(PBUNDLE)&lb); 
ptl.x = PAGE_OFFSET; 

ptl.y = (CurrentDI.cy - nSysFontHeight) - PAGE_OFFSET; 

GpiConve rt(hPS,CVTC_DEVICE,CVTC_WORLD,1,(PPOXNTL)&ptl); 

GpiMove(hPS,(PPOINTL)&ptl); 

ptl.x = CurrentDI.PhyPageSizel.cx + ptl.x; 

ptl.y = ptl.y - CurrentDI.PhyPageSizel.cy; 

GpiBox(hPS,DRO_OUTLINEFILL,(PPOINTL)&ptl,0,0); 

/* Outline the addressable portion of the page with a 
blue dashed line */ 
lb.lColor = RGB_BLUE; 
lb.usType = LINETYPE_SHORTDASH; 

GpiSetAttrs(hPS,PRIM_LINE,LBB_COLOR | LBB_TYPE,0,(PBUNDLE)&lb); 
ptl.x = PAGE_OFFSET; 

ptl.y = (CurrentDI.cy - nSysFontHeight) - PAGE_OFFSET; 
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GpiConvert(CurrentDI.hClientPS, CVTC_DEVICE, CVTCJ/VORLD,1, 
(PPOINTL)&ptl); 

ptl.x += CurrentDI.PrintOffsetSizel.cx; 
ptl.y -= CurrentDI.PrintOffsetSizel.cy; 

GpiMove(hPS,(PPOINTL)&ptl); 

ptl.x = CurrentDI.PageSizel.cx + ptl.x; 

ptl.y = ptl.y - CurrentDI.PageSizel.cy; 

GpiBox(hPS j DRO_OUTLINE,(PPOINTL)&ptl,0,0); 


PPRQINF03 APIENTRY enum_print_queues(HWND hWnd,HWND hWndLBox, 

PULONG pulSize 3 PULONG pulCount, 
PULONG pulCurrent) 

/*.*\ 


This function will enumerate the installed print queues and add 
their description to hWndLBox. The function returns a pointer 
to an array of PPRQINF03 structures if successful. The number of 
entries in the array and the total size of the allocated memory 
is returned in the pulCount and pulSize parameters respectfully. 
The index of the current application default queue is returned in 
the pulCurrent parameter. 


\*.*/ 

{ 

ULONG cReturned, cTotal, ulSize; 

int i; 

PSZ pName; 


PPRQINF03 pQueuelnfo = 0; 
ulSize = 0; 

SplEnumQueue(0,3,0,0L,(PULONG)&cReturned,(PULONG)&cTotal, 
(PULONG)&ulSize 3 0); 

if (pulCount) 

*pulCount = cTotal; 

if (!cTotal) 

post_error(hWnd,ID_NOQUEUE_ERROR); 
else if (!DosSubAlloc(pMem 3 (PPVOID)&pQueueInfo,ulSize)) 

{ 

/* Set the size in the return parameter */ 

*pulSize = ulSize; 

SplEnumQueue(0,3,pQueuelnfo,ulSize,(PULONG)&cReturned, 

(PULONG)&cTotal,(PULONG)&uISize,0); 

WinEnableWindowUpdate(hWndLBox,FALSE); 

WinSendMsg (hWndLBox,LM_DELETEALL,0,0); 


605 





Real-World Programming for \Joi Z> 2.1 


for (i = 0;i < (int)cTotal; i++) 

{ 

/* if the queue description is a NULL string then use the 
the queue name so the dialog won't have a blank entry */ 
if (*pQueueInfo[i].pszComment) 

pName = pQueuelnfo[i].pszComment; 

else 

pName = pQueuelnfo[i].pszName; 

WinSendMsg (hWndLBox,LM_INSERTITEM,(MPARAM)LIT_END, 

(MPARAM)pName); 

if (strcmp(CurrentDI.szQueueDesc,pName) == 0) 

/* This is the current application default */ 
*pulCurrent = i; 

} 

WinEnableWindowUpdate(hWndLBox,TRUE); 

} 

return(pQueuelnfo); 


VOID APIENTRY get_job_properties(PPRQINF03 pQueuelnfo,PDDINFO pDDInfo, 

ULONG ulOption) 


This function will query or post job properties for the queue 
identified by the pQueuelnfo parameter. ulOptioh should be set 
to DPDM_QUERYJOBPROP or DPDM_POSTJOBPROP. 


int i; 

PSZ pszTemp; 

CHAR szDriverName[MAX_DEVICENAME]; 

CHAR szDeviceName[MAX_DEVICENAME]; 

if ((i = strcspn(pQueuelnfo->pszDriverName,".")) != 0) 

strncpy((PSZ)szDriverName,(PSZ)pQueueInfo->pszDriverName,i); 
szDriverName[i] = '\0 1 ; 

strcpy((PSZ)szDeviceName,(PSZ)&pQueueInfo->pszDriverName[i + 1]); 

} 

else 

strcpy((PSZ)szDriverName, pQueuelnfo->pszDriverName); 
*szDeviceName = '\0'; 
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pszTemp = (PSZ)strchr(pQueueInfo->pszPrinters, 1 , 1 ); 
if ( pszTemp ) 

{ 

*pszTemp = '\0 1 ; 

} 

if (pDDInfo->pDrivData == 0) 

{ 

/* Allocate memory for the driver data */ 
pDDInfo->lSizeDD = DevPostDeviceModes(hab,0,szDriverName, 
szDeviceName,pQueuelnfo->pszPrinters,ulOption); 

DosSubAlloc(pMem,(PPVOID)&pDDInfo->pDrivData,pDDInfo->lSizeDD ); 
pDDInfo->pDrivData->cb = sizeof(DRIVDATA); 
pDDInfo->pDrivData->lVersion = 0 ; 

stropy(pDDInfo->pDrivData->szDeviceName,szDeviceName); 

DevPostDeviceModes(hab,pDDInfo->pDrivData,szDriverName,szDeviceName, 
pQueueInfo->pszPrinters,ulOption); 

} 


VOID APIENTRY get_page_metrics(PDEVICEINFO pDI) 


This function will initialize the physical and printable page 
sizes for the information DC in the pDI parameter. 


POINTL PtlRes; 

PHCINFO pHCInfo; 
int i; 

GpiQueryPS(pDI->hInfoPS,(PSIZEL)&pDI->PageSizel); 
pDI->lSizeHC = DevOueryHardcopyCaps(pDI->hInfoDC, 0 , 0 , 0 ); 
if ( (pDI->lSizeHC > 0) && 

(DosSubAlloc(pMem,(PPVOID)&pDI->pHCInfo, 
pDI->lSizeHC * sizeof(HCINFO)) == 0 ) ) 

{ 

DevQueryHardcopyCaps(pDI->hlnfoDC,0,pDI->lSizeHC,pDI->pHCInfo); 

pHCInfo = pDI->pHCInfo; 

for (i = 0; i < pDI->lSizeHC; i++) 

{ 

if (pHCInfofi].flAttributes & HCAPS_CURRENT) 

{ 

/* Calculate the physical page size */ 

DevQueryCaps (pDI ->hInfoDC,CAPS_HORIZONTAL_RESOLUTION,1 L 
(PLONG) &PtlRes.x); 


607 





Real-World Programming 


for OS/2 2.1 


DevQueryCaps (pDI->hInfoDC,CAPS_VERTICAL_RES0LUTI0N,1L, 
(PLONG) &PtlRes.y); 

/* Convert from millimeters to pixels */ 
pDI->PhyPageSizel.cx = (PtlRes.x * pHCInfo[i].cx) / 1000; 
pDI->PhyPageSizel.cy = (PtlRes.y * pHCInfo[i].cy) / 1000; 
/* Convert from device to world coordinate space */ 
GpiConvert(pDI->hInfoPS,CVTC_DEVICE,CVTC_WORLD,1, 

(PPOINTL)&pDI->PhyPageSizel); 

pDI ->PrintOffsetSizel.cx = 

(PtlRes.x * pHCInfo[ij.xLeftClip) / 1000; 
pDI->PrintOffsetSizel.cy = 

(PtlRes.y * pHCInfo[i].yBottomClip) / 1000; 

/* Convert from device to world coordinate space */ 
GpiConvert(pDI->hInfOPS,CVTC_DEVICE,CVTC_WORLD,1, 
(PPOINTL)&pDI->PrintOffsetSizel); 
break; 

} 

} 

} 

else 

{ 

pDI->pHCInfo = 0; 
pDI->lSizeHC = 0; 

} 


HPS APIENTRY init_app(HWND hWnd) 

/*.*\ 


This function is called on program startup to intialize the 
CurrentDI variable based on the system default queue. A PS is 
created for the client window, the default viewing matrix is 
modified, and the PS is changed from indexed to RGB mode. 


{ 

PPRQINF03 pPrq3; 

ULONG ulSize; 

char szTemp[MAX_BUFF]; 

PSZ pStr; 

ULONG ulNeeded; 

MATRIXLF matlfDefView; 

memset(&CurrentDI,0,sizeof(DEVICEINFO)); 
CurrentDI.ICopies = 1; 

CurrentDI.IPriority = 50; 


*/ 
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/* Query the default printer */ 

ulSize = PrfQueryProfileString(HINI_PROFILE,"PM_SP00LER","QUEUE", 
0,szTemp,MAX_BUFF); 

if (ulSize) 

{ 

pStr = (PSZ)strchr(szTemp,';'); 

*pStr = 0; 

SplQueryQueue(0,szTerap,3,0,0,&ulNeeded); 

if (ulNeeded && !(DosSubAlloc(pMem,(PPV0ID)&pPrq3,ulNeeded))) 

{ 

SplQueryQueue(0,szTemp,3,pPrq3,ulNeeded,&ulNeeded); 
get_j ob_properties(pPrq3,(PDDINFO)&CurrentDI.ISizeDD, 
DPDM_QUERYJOBPROP); 
create_info_DC(pPrq3,&CurrentDI); 

DosSubFree(pMem,pPrq3,ulNeeded); 

CurrentDI.hClientDC = WinOpenWindowDC(hWnd); 

CurrentDI.hClientPS = GpiCreatePS(hab,CurrentDI.hClientDC, 
(PSIZELJ&CurrentDI.ClientSizel, 

PUJ.OMETRIC | GPIF_LONG | GPIT_NORMAL | GPIA_ASSOC); 

/* Scale the page to 50% */ 

GpiQueryDefaultViewMatrix(CurrentDI.hClientPS,9,&matlfDefView); 

matlfDefView.fxMlI =MAKEFIXED(0,32768); 

matlfDefView.fxM22 = MAKEFIXED(0,32768); 

matlfDefView.1M31 = PAGE_OFFSET; 

matlfDefView.1M32 = 0; 

GpiSetDefaultViewMatrix(CurrentDI.hClientPS,9,&matlfDefView, 
TRANSFORM_REPLACE); 

/* Create an RGB color table */ 

GpiCreateLogColorTable (CurrentDI.hClientPS,LCOL_RESET, 
LC0LF_RGB,0,0,NULL); 

IColorWorkSpace = WinQuerySysColor(HWND_DESKTOP, 
SYSCLR_APPWORKSPACE,0); 

} 

} 

if (!CurrentDI.hlnfoDC) 

{ 

/* Disable print menus */ 

HWND hMenu = WinWindowFromID(WinQueryWindow(hWnd,QW_PARENT), 
FID_MENU); 

WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_CHOOSE_PRINTER,TRUE), 

MPFR0M2SH0RT(MIA_DISABLED,FALSE)); 
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WinSendMsg (hMenu,MM_SETITEMATTR, 

MPFR0M2SH0RT(IDM_PRINTER_INF0 3 TRUE), 
MPFR0M2SH0RT(MIA_DISABLED,FALSE)); 
WinSendMsg (hMenu,MM_SETITEMATTR, 
MPFR0M2SH0RT(IDM_PRINT,TRUE), 
MPFR0M2SH0RT(MIA_DISABLED , FALSE)); 

/* Message box */ 

post_error(hWnd,ID_ERR_NODEF_PRINTERS); 

} 

return (CurrentDI.hlnfoDC); 


USHORT APIENTRY post_error(HWND hWnd 3 USHORT usErrorlD) 

/*.*\ 


This is a utility function which will post a message box with 
a string loaded from the resource file. 



WinLoadString (hab 3 0 3 usErrorID 3 MAX_BUFF 3 szBuff1); 
return (WinMessageBox(HWND_DESKTOP,hWnd,(PSZ)szBuffl , 


(PSZ)"Error" 3 0 3 MB_OK | MB_ICONHAND | MB_APPLMODAL)); 

} 


void APIENTRY process_command(HWND hWnd,MPARAM mpl,MPARAM mp2) 

/*.*\ 


All WM_COMMAND messages received by the client window will be 
processed here. 


\* . */ 

{ 

switch(SH0RT1FR0MMP(mp1)) 

{ 

case IDM_DISP_BLANK: 
case IDM_DISP_BOX: 
case IDM_DISP_ELLIPSE: 

WinSendMsg (hMenu 3 MM_SETITEMATTR 3 MPFROM2SHORT(usDraw,TRUE), 
MPFR0M2SH0RT(MIA_CHECKED 3 FALSE)); 
usDraw = SHORT1FROMMP(mpl); 

WinSendMsg (hMenu,MM_SETITEMATTR 3 MPFR0M2SH0RT(usDraw 3 TRUE) 3 
MPFROM2SHORT(MIA_CHECKED 3 MIA_CHECKED)); 

WinlnvalidateRect(hWndClient 3 0 3 FALSE); 
break; 

case IDM_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 
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case IDM_CHOOSE_PRINTER: 

/* Display the queue selection dialog */ 

WinDlgBox(HWND_DESKTOP,hWndFrame,(PFNWP)SelectPrinterDlgProc,0, 
SELECT_PRINTER_DLG,(PVOID)0); 
break; 

case IDM_PRINTER_INFO: 

/* Display the queue information dialog */ 

WinDlgBox(HWND_DESKTOP,hWndFrame,(PFNWP)PrintInfoDlgProc,0, 
QUEUE_INFO_DLG,(PVOID)0); 
break; 

case IDM_PRINT: 

/* Confirm the print operation and print */ 

if (WinDlgBox(HWND_DESKTOP,hWndClient,PrintDlgProc,0,PRINT_DLG, 
(PVOID)0) == DID_0K) 

{ 

WinDlgBox(HWND_DESKTOP,hWndClient,PrintStatusProc,0, 
PRINT_STATUS_DLG,(PV0ID)&mp1); 

} 

break; 

case IDM_PRINT_THREAD: 

/* Confirm the print operation and print in a thread */ 
if (WinDlgBox(HWND_DESKTOP,hWndClient,PrintDlgProc,0,PRINTEDLG, 
(PVOID)0) == DID_0K) 

{ 

WinLoadDlg(HWND_DESKTOP 3 hWndClient,PrintStatusProc,0, 
PRINT_STATUS_DLG,(PV0ID)&mp1); 

} 

break; 
default: 
break; 

} 

return; 
mp2; 
hWnd; 

} 

#if def IBMC 

#pragma linkage(process_print, system) 

#endif 

void APIENTRY process_print(HWND hPrintStatusDlg) 

/*.*\ 


This function perfoms the actual printing. A copy of the current 
device settings are copied to an allocated memory block and a 
print DC is created. If successful, the printing is done and the 
job is completed. The print status dialog is updated via posted 
WM_PRINT_STATUS messages. 


\* 


/ 
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PDEVICEINFO pDI; 

if (DosSubAlloc(pMem,(PPVOID)&pDI,sizeof(DEVICEINFO)) == 0) 
{ 

*pDI = CurrentDI; 

if (create_print_DC(pDI)) 

{ 

WinPostMsg(hPrintStatusDlg,WM_PRINT_STATUS, 

(MPARAM)JOB_STARTED, 0); 
draw_page(pDI->hPrintPS); 

DevEscape(pDI->hPrintPS , DEVESC_ENDDOC,0,0,0,0); 
WinPostMsg(hPrintStatusDlg,WM_PRINT_STATUS 3 
(MPARAM)JOB_FINISHED, 0) ; 

GpiAssociate(pDI->hPrintPS,0); 
GpiDestroyPS(pDI->hPrintPS); 

DevCloseDC(pDI->hPrintDC); 

} 

else 

WinPostMsg (hPrintStatusDlg ,WM_PRINT__STATUS 3 
(MPARAM)JOB_FAILED,0); 

DosSubFree(pMem,pDI,sizeof(DEVICEINFO)); 

} 


void APIENTRY process_size(MPARAM mpl,MPARAM mp2) 

{ 

POINTL ptl; 

MATRIXLF matlfDefView; 

CurrentDI.cx = SHORT1FROMMP(mp2); 

CurrentDI.cy = SH0RT2FR0MMP(mp2); 

WinSetWindowPos (hHintWnd,HWND_T0P,0,0,SHORT1FROMMP(mp2), 
nSysFontHeight,SWP_SIZE | SWP_M0VE); 

/* Reset the default view matrix before converting client size */ 
ptl.x = PAGE_OFFSET; 

ptl.y = (CurrentDI.cy - nSysFontHeight) - PAGE_OFFSET + 1; 
GpiQueryDefaultViewMatrix(CurrentDI.hClientPS,9,&matlfDefView ); 
matlfDefView.1M31 = 0; 

matlfDefView.1M32 =0; 

GpiSetDefaultViewMatrix(CurrentDI.hClientPS,9,&matlfDefView, 
TRANSFORM_REPLACE); 

GpiConvert(CurrentDI.hClientPS,CVTC_DEVICE,CVTC_WORLD,1, 

(PPOINTL)&ptl); 
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ptl.y = (ptl.y - CurrentDI.PhyPageSizel.cy) + 

CurrentDI.PrintOffsetSizel.cy; 
ptl.x = ptl.x + CurrentDI.PrintOffsetSizel.cx; 
matlfDefView.lM31 = (LONG)((float)ptl.x * 0.5); 
matlfDefView.1M32 = (LONG)((float)ptl.y * 0.5); 
GpiSetDefaultViewMatrix(CurrentDI.hClientPS,9,&matIfDefView, 
TRANSFORM_REPLACE); 
return; 
mpl; 


MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

/*.*\ 


This is the application callback which handles the messages 
necessary to maintain the client window. 


\*.*/ 


HPS 

hPS; 

RECTL 

Recti; 

TID 

tid; 

BOOL 

bHandled = TRUE 

MRESULT 

mReturn = 0; 

switch 

(msg) 


{ 

case WM^CREATE: 

hPS = init_app(hWnd); 
break; 

case WM_COMMAND: 

process_command(hWnd,mp1,mp2); 
break; 

case WM_PAINT: 

hPS = WinBeginPaint (hWnd,CurrentDI.hClientPS,(PRECTL)&Rectl); 
WinFillRect(hPS,(PRECTL)&Rectl,IColorWorkSpace); 
draw_page_background(hPS); 
draw_page(hPS); 

WinEndPaint (hPS); 
break; 

case WM_ERASEBACKGROUND: 
mReturn = MRFROMLONG(1L); 
break; 

case WM_MENUSELECT: 

display_hint(SHORT1FROMMP(mpl)); 

bHandled = FALSE; 

break; 
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case WM_SIZE: 

process_size(mp1,mp2); 
break; 

case WM_START_PRINT: 

if (SHORT1FROMMP(mp2) == IDM_PRINT) 
process_print((HWND)mpl); 
else 

DosCreateThread(&tid,(PFNTHREAD)process_print,(ULONG)mpl, 
0,0x2000); 
break; 
default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 


MRESULT EXPENTRY PrintDlgProc(HWND hWndDlg,ULONG ulMessage,MPARAM mpl, 

MPARAM mp2) 


This function will display the print confirmation dialog box. It 
allows the user to verify the print destination and set the job 
priority and print copies. 


HWND hWnd; 

ULONG ulSelect; 

switch (ulMessage) 

{ 

case WM_INITDLG: 

center_window(hWndDlg); 

hWnd = WinWindowFromID(hWndDlg,DID_PRINTER); 
WinSetWindowText(hWnd,CurrentDI.szQueueDesc); 

WinSendMsg(hWnd,EM_SETREADONLY,(MPARAM)TRUE,0); 

hWnd = WinWindowFromID (hWndDlg, DID_DOCUMENT) ; 

WinLoadString(hab,0,IDS_JOB_TITLE,sizeof(szBuff1),szBuff1); 
WinSetWindowText(hWnd,szBuff1); 

WinSendMsg(hWnd,EM_SETREADONLY,(MPARAM)TRUE,0); 
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/* Set the limits to the valid range for a queue processor */ 
hWnd = WinWindowFromID(hWndDlg,DID_COPIES); 

WinSendMsg(hWnd,SPBM_SETLIMITS,(MPARAM)999,(MPARAM) 1); 
WinSendMsg(hWnd,SPBM_SETCURRENTVALUE, 

MPFROMLONG(CurrentDI.ICopies),0); 

WinSetFocus(HWND_DESKTOP,hWnd); 

/* Initialize the priority spinner control */ 
hWnd = WinWindowFromID(hWndDlg,DID_PRIORITY); 

WinSendMsg (hWnd,SPBM_SETTEXTLIMIT,(MPARAM)9L,(MPARAM)0L); 
WinSendMsg (hWnd,SPBM_SETARRAY,(MPARAM)pszPriorities,(MPARAM)3); 
WinSendMsg (hWnd,SPBM_SETCURRENTVALUE,(MPARAM)1,(MPARAM)0L); 
return ((MRESULT)TRUE); 
case WM_COMMAND: 

switch (SH0RT1FROMMP(mpl)) 

{ 

case DID_OK: 

hWnd = WinWindowFromID(hWndDlg,DID_COPIES); 

WinSendDlgltemMsg(hWndDlg,DID_COPIES,SPBM_QUERYVALUE, 

&CurrentDI.ICopies,MPFR0M2SH0RT(0,SPBQ_UPDATEIFVALID)); 
/* Query selection index from spinner */ 
if (WinSendDlgltemMsg (hWndDlg, did_priority, 

SPBM_QUERYVALUE, (MPARAM)&ulSelect, 0L)) 

CurrentDI.IPriority = lPriority[ulSelect]; 

else 

CurrentDI.IPriority = 50; 

WinDismissDlg(hWndDlg,DID_0K); 
return 0; 

} 

break; 

case WM_CONTROL: 

switch (SH0RT1FR0MMP(mp1)) 

{ 

case DID_PRIORITY: 

if (HIUSHORT(mpl) == SPBN_ENDSPIN) 

{ 

/* Query selection index from spinner */ 
if(WinSendDlgltemMsg (hWndDlg, DID_PRIORITY, 
SPBM_QUERYVALUE, (MPARAM)&ulSelect, 0L)) 

CurrentDI.IPriority = IPriority[ulSelect]; 
else 

CurrentDI.IPriority = 50; 

} 

break; 

} 

break; 

} 


615 



Real-World Programming for U5/ JL 2.1 


return (WinDefDlgProc(hWndDlg,ulMessage,mpl,mp2)); 

} 


MRESULT EXPENTRY PrintStatusProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2) 

/*.-.*\ 


This function is the callback for the print job status dialog. 
When the WM_INITDLG message is received a WM_START_PRINT message 
is posted to the client window requesting the print job to be 
started. When the WM_PRINT_STATUS message is received the text in 
the status window is updated accordingly. 


\*.*/ 

{ 

HWND hWnd; 

LONG IColor; 

switch (ulMessage) 

{ 

case WM_INITDLG: 

center_window(hWndDlg); 

hWnd = WinWindowFromID(hWndDlg,DID_OK); 

WinShowWindow(hWnd,FALSE); 

hWnd = WinWindowFromID(hWndDlg,DID_JOBNAME); 

WinLoadString(hab,0,IDS_JOB_TITLE,sizeof(szBuff1),szBuff1); 
WinSetWindowText(hWnd,szBuff1); 

hWnd = WinWindowFromID(hWndDlg,DID_PRINTER); 

WinSetWindowText(hWnd,CurrentDI.szQueueDesc); 

hWnd = WinWindowFromID(hWndDlg,DID_STATUS); 

WinSetWindowText(hWnd,"Initializing Printer"); 

WinPostMsg(hWndClient,WM_START_PRINT, (MPARAM)hWndDlg, 

(MPARAM)*(PUL0NG)mp2); 
break; 

case WM_PRINT_STATUS: 

hWnd = WinWindowFromID(hWndDlg,DID_STATUS); 
switch(SH0RT1FROMMP(mpl)) 

{ 

case JOB_STARTED: 

WinSetWindowText(hWnd,"Starting Print Job"); 
break; 

case JOB_CANCELED: 

WinSetWindowText(hWnd,"Print Job Cancelled"); 
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WinPostMsg (hWndDlg ,WM_C01VIMAND, (MPARAM)DID_OK,0) ; 
break; 

case JOB_FAILED: 

IColor = CLR_RED; 

WinSetPresParam(hWnd,PP_FOREGROUNDCOLORINDEX,sizeof(PLONG), 
&lColor); 

WinSetWindowText(hWnd,"Print Job Failed"); 
WinAlarm(HWND_DESKTOP,WA_ERR0R); 

/* Switch the cancel button to an ok button */ 
hWnd = WinWindowFromID(hWndDlg,DID_0K); 

WinShowWindow(hWnd,TRUE); 

hWnd = WinWindowFromID(hWndDlg,DID_CANCEL); 

WinShowWindow(hWnd,FALSE); 
break; 

case JOB_FINISHED: 

WinSetWindowText(hWnd,"Print Job Finished"); 

WinPostMsg(hWndDlg,WM_COMMAND,(MPARAM)DID_0K,0); 
break; 

} 

break; 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_CANCEL: 

hWnd = WinWindowFromID(hWndDlg,DID_STATUS); 

WinSetWindowText(hWnd,"Canceling Print Job"); 

WinPostMsg(hWndClient,WM_ABORT_PRINT,0,0); 
return 0; 
case DID_0K: 

WinDismissDlg(hWndDlg,DID_0K); 
return 0; 

} 

break; 

} 

return (WinDefDlgProc(hWndDlg,ulMessage,mp1,mp2)); 

} 


MRESULT EXPENTRY SelectPrinterDlgProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2) 

/* *\ 


This function is the callback for the printer selection dialog. 
It will fill a list box with installed queue entries and post 
job .properties when requested. If OK is selected, the current 
queue selection, along with it's last job properties, is set in 
the CurrentDI variable. 


\*.-.---*/ 

{ 
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static PPRQINF03 
static ULONG 
static HWND 
static BOOL 
static PDDINFO 
static ULONG 
RECTL Recti; 
int i; 

PDDINFO pDDI; 


pQueuelnfo; 
ulSize = 0; 
hWndLBox; 
bRedraw = FALSE; 
pDDInfo; 
ulCount; 


SHORT sSelection; 
ULONG ulCurrent; 


switch (ulMessage) 

{ 

case WM_INITDLG: 

center_window(hWndDlg); 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
if (!(pQueuelnfo = enum_print_queues(hWndDlg,hWndLBox, 

(PULONGJ&ulSize,(PULONG)&ulCount,(PULONG)&ulCurrent))) 
WinDismissDlg(hWndDlg,DID_0K); 
else if (!DosSubAlloc(pMem,(PPVOID)&pDDInfo,ulCount * 
sizeof(DDINFO))) 

{ 

memset(pDDInfo,0,ulCount * sizeof(DDINFO)); 

/* Preload the entry for the current printer with the 
saved values from CurrentDI */ 

(pDDInfo + ulCurrent)->pDrivData = CurrentDI.pDrivData; 
(pDDInfo + ulCurrent)->lSizeDD = CurrentDI.ISizeDD; 

/* Select the current entry in the list box */ 

WinSendMsg (hWndLBox,LM_SELECTITEM,MPFROMSHORT(ulCurrent), 
MPFROMSHORT(TRUE)); 

} 

break; 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_0K: 

sSelection = (USHORT)WinSendMsg (hWndLBox,LM_QUERYSELECTION, 
MPFROMSHORT(LIT_FIRST),0); 
if (!(pDDInfo + sSelection)->pDrivData) 

{ 

get_Job_properties(&pQueueInfo[sSelection], 
&pDDInfo[sSelection],DPDM_QUERYJOBPROP); 
bRedraw = TRUE; 

} 

if ((pDDInfo + sSelection)->pDrivData) 

{ 
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/* If we are changing application default printers, 
free up current driver data and replace it with 
the driver data for the selected printer. */ 
if ( CurrentDI.pDrivData && 

(CurrentDI.pDrivData != 

(pDDInfo + sSelection)->pDrivData) ) 

{ 

DosSubFree(pMem,CurrentDI.pDrivData,CurrentDI.ISizeDD); 
CurrentDI.pDrivData = (pDDInfo + sSelection)->pDrivData; 
CurrentDI.ISizeDD = (pDDInfo + sSelection)->lSizeDD; 

} 

(pDDInfo + sSelection)->pDrivData = 0; 

(pDDInfo + sSelection)->lSizeDD = 0; 

} 

create_info_DC(&pQueueInfo[sSelection], 
(PDEVICEINFO)&CurrentDI); 

WinDismissDlg(hWndDlg,DID_OK); 

pDDI = pDDInfo; 

for (i =0; i < (int)ulCount;i++) 

{ 

if ((pDDI + i)->pDrivData) 

DosSubFree(pMem,(pDDI + i)->pDrivData, 

(pDDI + i)->lSizeDD); 

} 

DosSubFree(pMem,pDDInfo,ulCount * sizeof(DDINFO)); 
DosSubFree(pMem,pQueueInfo,ulSize); 
if (bRedraw) 

{ 

WinQueryWindowRect(hWndClient,(PRECTL)&Rectl); 

WinSendMsg(hWndClient,WM_SIZE,0, 

MPFR0M2SH0RT(Recti.xRight,Recti.yTop)); 

WinInvalidateRect(hWndClient,0,TRUE); 

} 

break; 

case DID_CANCEL: 

WinDismissDlg(hWndDlg,DID_CANCEL); 
pDDI = pDDInfo; 

for (i = 0; i < (int)ulCount;i++) 

{ 

/* Free up any allocated driver data except the 
current application default */ 
if ( (pDDI + i)->pDrivData && 

(CurrentDI.pDrivData != (pDDI + i)->pDrivData) ) 
DosSubFree(pMem,(pDDI + i)->pDrivData, 

(pDDI + i)->lSizeDD); 

} 

DosSubFree(pMem,pDDInfo,ulCount * sizeof(DDINFO)); 

DosSubFree(pMem,pQueueInfo,ulSize); 
break; 
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case DID_JOBPROPS: 

sSelection = (USHORT)WinSendMsg (hWndLBox , LM_QUERYSELECTION, 
MPFROMSHORT(LIT_FIRST),0); 
if (sSelection 1= LIT_N0NE) 

{ 

get_job_properties(&pQueueInfo[sSelection], 

&pDDInfo[sSelection],DPDM_POSTJOBPROP); 
bRedraw = TRUE; 

} 

return 0; 

} 

break; 
default: 
break; 

} 

return (WinDefDlgProc(hWndDlg,ulMessage,mp1,mp2)); 


PRNTINFO.C 


/* 


Printing Sample Program 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCLJVIN 

#define INCL_GPI 

#define INCL_DEV 

#define INCL_SPL 

#define INCL_SPLDOSPRINT 

#include <os2.h> 

#include <string.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include "prnt.h" 
#include "dialog.h" 


extern 

HAB 

hab; 


extern 

CHAR 

szTemp[] 

extern 

PVOID 

pMem: 

i 

CHAR 

szYes[] = ' 

'Yes 

CHAR 

szNo[; 

i = 1 

■No" 
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void APIENTRY free_info_DCs(PDEVICEINFO pDI,UL0NG ulCount) 

/*..*\ 

This function will walk the array of DEVICEINFO structures destroy¬ 
ing information device contexts and freeing memory allocated for 
form arrays. 


\*.*/ 

{ 

int i; 

for (i = 0; i < (int)ulCount;i++) 

{ 

if ((pDI + i)->hlnfoPS) 

{ 

GpiAssociate((pDI + i)->hlnfoPS 3 0); 

GpiDestroyPS((pDI + i)->hInfoPS); 
pDI->hInfoPS = 0; 

DevCloseDC((pDI + i)->hlnfoDC); 

(pDI + i)->hInfoDC = 0; 

} 

if ((pDI + i)->pHCInfo) 

{ 

DosSubFree(pMem,(pDI + i)->pHCInfo,((pDI + i)->lSizeHC * 
sizeof(HCINFO))); 

(pDI + i)->pHCInfo = 0; 

(pDI + i)->lSizeHC = 0; 

} 

} 

} 


void APIENTRY query_device_info(HWND hWndDlg,PPRQINF03 pPrq3 3 

PDEVICEINFO pDI) 


/* 


*\ 


This function will update fields of the queue info dialog based 
on the supplied pPrq3 and pDI structures. 


\*. - .*/ 

{ 

HWND hWnd; 

int index; 

PHCINFO pHCI; 

LONG IDevCaps[CAPS_RASTER_CAPS +1]; 

CHAR szT emp[MAX_BUFF]; 

/* Update the device and default printer info */ 
hWnd = WinWindowFromID(hWndDlg,DID_QUEUE_NAME); 

WinSetWindowText(hWnd 3 pPrq3->pszName); 
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hWnd = WinWindowFromlD(hWndDlg , DID_DEFAULT_DEVICE); 
WinSetWindowText(hWnd,pPrq3->pszDriverName); 

hWnd = WinWindowFromID(hWndDlg,DID_PRINTERS); 

WinSetWindowText(hWnd,pPrq3->pszPrinters); 

/* Update the queue priority */ 

hWnd = WinWindowFromlD(hWndDlg,DID_PRIORITY); 

index = ((pPrq3->uPriority > 7) ? ID_PRIORITY_HIGH : 

(pPrq3->uPriority > 3) ? ID_PRIORITY_DEF : 
ID_PRIORITY_MIN); 

WinLoadString (hab,0,index,MAX_BUFF,szTemp); 

WinSetWindowText(hWnd,szTemp); 

/* Update the queue status */ 

hWnd = WinWindowFromlD(hWndDlg,DID_STATUS); 

index = ((pPrq3->fsStatus == PRQ3_PAUSED) ? ID_STATUS_HELD : 

(pPrq3->fsStatus == PRQ_PENDING) ? ID_STATUS_PEND : 
ID_STATUS_NORM); 

WinLoadString (hab,0,index,MAX_BUFF,szTemp); 

WinSetWindowText(hWnd,szTemp); 

/* Update the number of jobs in the queue */ 
hWnd = WinWindowFromlD(hWndDlg,DID_NUMBER_JOBS); 
itoa(pPrq3->cJobs,szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

/* Update the queue start and end time */ 
hWnd = WinWindowFromID(hWndDlg,DID_START_TIME); 
index = (pPrq3->uStartTime > 779) ? pPrq3->uStartTime - 720 : 
pPrq3->uStartTime; 

sprintf(szTemp,"%2i:%02i %s",index / 60, 

pPrq3->uStartTime % 60,(pPrq3->uStartTime > 779) ? "PM" : 

"AM"); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_END_TIME); 
index = (pPrq3->uUntilTime > 779) ? pPrq3->uUntilTime - 720 : 
pPrq3->uUntilTime; 

sprintf(szTemp,"%2i:%02i %s",index / 60, 

pPrq3->uUntilTime % 60,(pPrq3->uUntilTime > 779) ? "PM" : 

"AM" ); 

WinSetWindowText(hWnd,szTemp); 

/* Query the forms available */ 
if ((!pDI->pHCInfo) && 

(pDI->lSizeHC = DevQueryHardcopyCaps(pDI->hInfoDC,0,0,0)) > 0) 

{ 
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/* Only query the forms the first time */ 
if (DosSubAlloc(pMem,(PPVOID)&pDI->pHCInfo,(pDI->lSizeHC * 
sizeof(HCINFO)))) 
pDI->pHCInfo = 0; 

else 

DevQueryHardcopyCaps(pDI->hlnfoDC,0,pDI->lSizeHC, 
pDI->pHCInfo); 

} 

if (pDI->pHCInfo) 

{ 

hWnd = WinWindowFromID(hWndDlg,DID_FORMS); 
WinEnableWindowllpdate (hWnd, FALSE); 
pHCI = pDI->pHCInfo; 

WinSendMsg (hWnd,LM_DELETEALL,0,0); 

for (index = 0; index < pDI->lSizeHC; index++) 

{ 

WinSendMsg (hWnd,LM_INSERTITEM,(MPARAM)LIT_END, 

(pHCI + index)->szFormname); 

} 

WinEnableWindowllpdate (hWnd, TRUE) ; 

WinSendMsg (hWnd,LM_SELECTITEM,(MPARAM)0,MPFROMSHORT(TRUE)) 

} 

/* Query all of the desired metrics */ 

DevQueryCaps (pDI->hInfoDC,CAPS_FAMILY,CAPS_RASTER_CAPS, 
(PLONG)&lDevCaps); 

/* Update the device technology */ 

hWnd = WinWindowFromID(hWndDlg,DID_TECHNOLOGY); 

WinLoadString (hab,0,lDevCaps[CAPS_TECHNOLOGY] + ID_TECH_BASE, 
MAX_BUFF,szTemp); 

WinSetWindowText(hWnd,szTemp); 

/* Update the device resolution */ 

hWnd = WinWindowFromID(hWndDlg,DID_CAPS_WIDTH); 

itoa(lDevCaps[CAPS_WIDTH],szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_CAPS_HEIGHT); 
itoa(IDevCaps[CAPS_HEIGHT],szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_HORZ_RES); 

itoa(IDevCaps[CAPS_HORIZONTAL_RESOLUTION],szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_VERT_RES); 
itoa(IDevCaps[CAPS_VERTICAL_RESOLUTION],szTemp,10); 
WinSetWindowText(hWnd,szTemp); 
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hWnd = WinWindowFromID(hWndDlg,DID_BITBLT); 

WinSetWindowT ext(hWnd, 

(IDevCaps[CAPS_RASTER_CAPS] & CAPS_RASTER_BITBLT) ? 
szYes : szNo); 

hWnd = WinWindowFromID(hWndDlg , DID_BANDING); 

WinSetWindowT ext(hWnd, 

(IDevCaps[CAPS_RASTER_CAPS] & CAPS_RASTER_BANDING) ? 
szYes : szNo); 

hWnd = WinWindowFromID(hWndDlg , DID_SETPEL); 

WinSetWindowText(hWnd, 

(IDevCaps[CAPS_RASTER_CAPS] & CAPS_RASTER_SET_PEL) ? 
szYes : szNo); 

hWnd = WinWindowFromID(hWndDlg,DID_RASTER_FONT); 

WinSetWindowT ext(hWnd, 

(IDevCaps[CAPS_RASTER_CAPS] & CAPS_RASTER_FONTS) ? 
szYes : szNo); 

hWnd = WinWindowFromID(hWndDlg,DID_KERNING); 

WinSetWindowT ext(hWnd, 

(IDevCaps[CAPS_ADDITIONAL_GRAPHICS] & 
CAPS_GRAPHICS_KERNING_SUPPORT) ? 
szYes : szNo); 

hWnd = WinWindowFromID(hWndDlg,DID_PALETTE); 

WinSetWindowT ext(hWnd, 

(IDevCaps[CAPS_ADDITIONAL_GRAPHICS] & CAPS_PALETTE_MANAGER) ? 
szYes : szNo); 


void APIENTRY query_form_info(HWND hWndDlg,PHCINFO pHCInfo) 


/*.*\ 

This function will update the form fields in the queue info dialog 
based on the form pointed to by pHCInfo. 

\*. .*/ 

{ 

HWND hWnd; 

int i; 

CHAR szTemp[MAX_BUFF]; 


hWnd = WinWindowFromID(hWndDlg,DID_FORM_CX); 
itoa(pHCInfo->cx,szTemp,10); 

WinSetWindowText(hWnd,szTemp); 
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hWnd = WinWindowFromID(hWndDlg,DID_FORM_CY); 
itoa(pHCInfo->cy,szTemp, 10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_LEFT_CLIP); 
itoa(pHCInfo->xLeftClip,szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_BOTTOM_CLIP); 
itoa(pHCInfo->yBottomClip,szTemp, 10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_RIGHT_CLIP); 
itoa(pHCInfo->xRightClip,szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID__TOP_CLIP); 
itoa(pHCInfo->yTopClip,szTemp,10); 

WinSetWindowText(hWnd,szTemp); 

hWnd = WinWindowFromID(hWndDlg,DID_FORM_ATTR); 
if (pHCInfo->flAttributes & HCAPS_CURRENT) 

{ 

WinLoadString (hab,0,ID_CAPS_CURRENT,MAX_BUFF,szTemp); 
if (pHCInfo->flAttributes & HCAPS_SELECTABLE) 

{ 

strcat(szTemp,", "); 
i = strlen (szTemp); 

WinLoadString (hab,0,ID_CAPS_SELECTABLE,MAX_BUFF - 
i,&szTemp[i]); 

} 

} 

else if (pHCInfo->flAttributes & HCAPS_SELECTABLE) 

WinLoadString (hab,0,ID_CAPS_SELECTABLE,MAX_BUFF,szTemp); 

else 

WinLoadString (hab,0,ID_CAPS_NONE,MAX_BUFF,szTemp); 
WinSetWindowText(hWnd,szTemp); 


MRESULT EXPENTRY PrintInfoDlgProc(HWND hWndDlg,ULONG ulMessage, 

MPARAM mpl,MPARAM mp2) 

/*.*\ 

This function is the callback for the queue and printer information 
dialog. It will fill a list box with installed queue entries and 
post job properties when requested. In addition the forms available 
on the selected queue are queried and added to a second list box. 
Details from the PRQINF03, HCINFO, and various device capablilities 
of the selected queue are displayed in the dialog. 


\*.*/ 

{ 
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static 

static 

static 

static 

static 

static 

SHORT 

SHORT 

HWND 

ULONG 

PHCINFO 


PPRQINF03 pQueuelnfo; 
PDEVICEINFO pDI = 0; 

ULONG ulSize = 0; 

ULONG ulDISize = 0; 

ULONG ulCount = 0; 

DDINFO DDInfo; 

sQueueSelect; 
sFormSelect; 
hWndLBox; 
ulCurrent; 
pHCI; 


switch (ulMessage) 

{ 

case WM_INITDLG: 

center_window(hWndDlg); 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
if (!(pQueuelnfo = enum_print_queues(hWndDlg,hWndLBox, 

(PULONG)&ulSize,(PULONG)&ulCount,(PULONG)&ulCurrent))) 
WinDismissDlg(hWndDlg,DID_0K); 

else 

{ 

DDInfo.ISizeDD = 0; 

DDInfo.pDrivData = 0; 

ulDISize = ulCount * sizeof(DEVICEINFO); 

DosSubAlloc(pMem,(PPVOID)&pDI,ulDISize); 
memset(pDI,0,ulDISize); 

WinSendMsg (hWndLBox,LM_SELECTITEM,MPFROMSHORT(ulCurrent), 
MPFROMSHORT(TRUE)); 

} 

break; 

case WM_COMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case DID_CANCEL: 
case DID_OK: 

free_info_DCs(pDI,ulCount); 

DosSubFree(pMem,pQueuelnfo,ulSize); 

DosSubFree(pMem,pDI,ulDISize); 

WinDismissDlg(hWndDlg,DID_0K); 
return 0; 

case DID_J0BPR0PS: 
case DID_UPDATE: 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
sQueueSelect = (USHORT)WinSendMsg (hWndLBox, 
LM_QUERYSELECTION,MPFROMSHORT(LIT_FIRST),0); 
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if (sQueueSelect != LIT_NONE) 

{ 

if (SH0RT1FROMMP(mpl) == DID_JOBPROPS) 

{ 

get_j ob_properties(&pQueueInfo[sQueueSelect], 
(PDDINFO)&DDInf0,DPDM_POSTJOBPROP); 
if (DDInfo.pDrivData) 

{ 

DosSubFree(pMem,DDInfo.pDrivData, 

DDInfo.ISizeDD); 

DDInfo.ISizeDD = 0; 

DDInfo.pDrivData = 0; 

} 

} 

free_info_DCs(pDI,ulCount); 

DosSubFree(pMem,pQueuelnfo,ulSize); 

DosSubFree(pMem,pDI,ulDISize); 
pDI = 0; 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
if (!(pQueuelnfo = enum_print_queues(hWndDlg, 

hWndLBox,(PULONG)&ulSize,(PULONG)&ulCount, 
(PULONG)&ulCurrent))) 

WinDismissDlg(hWndDlg,DID_0K); 

else 

{ 

ulDISize = ulCount * sizeof(DEVICEINFO); 
DosSubAlloc(pMem,(PPVOID)&pDI,ulDISize); 
memset(pDl,0,ulDISize); 

WinSendMsg (hWndLBox,LM_SELECTITEM, 

MPFROMSHORT(sQueueSelect),MPFROMSHORT(TRUE)); 

} 

} 

return 0; 
default: 
break; 

> 

break; 

case WM_CONTROL: 

if (SH0RT2FR0MMP(mp1) == LN_SELECT) 

{ 

switch (LOUSHORT(mpl)) 

{ 

case DID_QUEUE_NAMES: 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
sQueueSelect = (USHORT)WinSendMsg (hWndLBox, 
LM_QUERYSELECTION,MPFROMSHORT(LIT_FIRST),0); 
if (sQueueSelect != LIT_NONE) 

{ 




Real-World Programming for OS/2 2 ., 


if (!(pDI + sQueueSelect)->hInfoDC) 
create_info_DC( 

(PPRQINF03)&pQueueInfo[sQueueSelect], 
(PDEVICEINFO)&pDI[sQueueSelect]); 
query_device_info(hWndDlg, 

(PPRQINF03)&pQueueInfo[sQueueSelect], 
(PDEVICEINFO)&pDI[sQueueSelect]); 

} 

break; 

case DID_F0RMS: 

hWndLBox = WinWindowFromID(hWndDlg,DID_QUEUE_NAMES); 
sQueueSelect = (USHORT)WinSendMsg (hWndLBox, 
LM_QUERYSELECTION,MPFROMSHORT(LIT_FIRST),0); 

if ((pHCI = pDI[sQueueSelect].pHCInfo) != 0) 

{ 

hWndLBox = WinWindowFromID(hWndDlg,DID_F0RMS); 
sFormSelect = (USHORT)WinSendMsg (hWndLBox, 

LM_QUERYSELECTION,MPFROMSHORT(LIT_FIRST),0); 
if (sFormSelect != LIT_NONE) 

query_form_info(hWndDlg,&(pHCI[sFormSelect])) 

> 

break; 

} 

} 

break; 

} 

return (WinDefDlgProc(hWndDlg,ulMessage,mp1 ,mp2)); 

} 


PRNT.DEF 


NAME 

DESCRIPTION 

PROTMODE 

HEAPSIZE 

STACKSIZE 

EXPORTS 


PRNT WINDOWAPI 

'Print Sample Program Blain, Delimon, & English, 1993' 

4096 

32768 

AboutDlgProc 

ClientWndProc 

PrintlnfoDlgProc 

PrintStatusProc 

PrintDlgProc 

SelectPrinterDlgProc 
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PRNT.H 


/* 


Print Sample Header File 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (o) 1993 Blain, Delimon, and English 


*/ 


/* Stringtable ID's */ 


#define 

ID_APPNAME 

1 

#define 

ID_NOQUEUE_ERROR 

2 

#define 

ID_PRIORITY_HIGH 

3 

#define 

ID_PRIORITY_DEF 

4 

#define 

ID_PRIORITY_MIN 

5 

#define 

ID_STATUS_HELD 

6 

#define 

ID_STATUS_PEND 

7 

#define 

ID_STATUS_NORM 

8 

#define 

ID__CAPS_CURRENT 

9 

#define 

ID_CAPS_SELECTABLE 

10 

#define 

ID CAPS_N0NE 

11 

#define 

IDJTECHJ3ASE 

12 

#define 

I D__T E C H_U N KN OWN 

ID_‘ 

#define 

ID_TECH_PLOTTER 

ID_‘ 

#define 

ID_TECH_RAST_DISP 

ID ' 

#define 

ID TECH_RAST_PRT 

IDJ 

#define 

ID TECH RAST_CAM 

IDJ 

#define 

IDJTECH_POSTSCRIPT 

IDJ 

#define 

ID_ERR_NODEF_PRINTERS 

18 

#define 

ID_ERR_FAIL_DEV_QUERY 

19 

/* Menu 

ID'S */ 


#define 

IDM_FILE 

100 

#define 

IDM_CHOOSE_PRINTER 

101 

#define 

IDM_PRINT 

102 

#define 

IDM_PRINT_THREAD 

103 

#define 

IDM_AB0UT 

104 

#define 

IDM_DISPLAY 

200 

#define 

IDM DISP BLANK 

201 

#define 

IDM DISP BOX 

202 

#define 

IDM_DISP_ELLIPSE 

203 

#define 

IDM_DISP_X 

204 

#define 

IDM_PRINTER_INFO 

205 

/* Help 

hint string ID's */ 


#define 

IDS_JOB_TITLE 

105 

#define 

MAX_BUFF 

128 

#define 

MAX DEVICENAME 

32 


1 

2 

3 

4 

5 
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#define 

MAX_QUEUENAME 


10 

#define 

MAX_QUEUEDESC 


64 

#define 

MAX_DRIVERNAME 

128 

#define 

QUEUENAME_LENGTH 

10 


#define 

QUEUEDESC_LENGTH 

64 


#define 

DEVICENAME_LENGTH 

32 


#define 

DRIVERNAME_LENGTH 

128 

#define 

WM_ST ART_P RINT 

WM_ 

USER 

#define 

WM_ABORT_PRINT 

wm~ 

"USER+1 

#define 

WM_END_PRINT 

wm" 

JJSER+2 

#define 

WM_PRINT_STATUS 

wm] 

]uSER+3 

#define 

JOB_STARTED 

100 


#define 

JOB_CANCELED 

101 


#define 

JOB_FINISHED 

102 


#define 

JOB_FAILED 

103 


#define 

PAGE_OFFSET 

10 


typedef 

struct DEVICEINFO 




HDC 

hintoDC; 

HPS 

hlnfoPS; 

HDC 

hPrintDC; 

HPS 

hPrintPS; 

HDC 

hClientDC; 

HPS 

hClientPS; 

SIZEL 

PageSizel; 

SIZEL 

ClientSizel; 

SIZEL 

PhyPageSizel; 

SIZEL 

PrintOffsetSizel; 

LONG 

ICopies; 

LONG 

IPriority; 

CHAR 

szQueueDesc[MAX_QUEUEDESC]; 

CHAR 

szQueueName[MAX_QUEUENAME]; 

CHAR 

szDriverName[MAX_DRIVERNAME] 

LONG 

ISizeDD; 

PDRIVDATA 

pDrivData; 

PHCINFO 

pHCInfo; 

LONG 

ISizeHC; 

int 

cx; 

int 

cy; 


} DEVICEINFO; 

typedef DEVICEINFO *PDEVICEINFO; 
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typedef struct DDINFO 

{ 
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LONG ISizeDD; 

PDRIVDATA pDrivData; 
} DDINFO; 

typedef DDINFO *PDDINFO; 


VOID 

APIENTRY 

BOOL 

APIENTRY 

BOOL 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

PPRQINF03 

APIENTRY 

void 

APIENTRY 

VOID 

APIENTRY 

VOID 

APIENTRY 

HPS 

APIENTRY 

USHORT 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 

void 

APIENTRY 


center_window(HWND); 

create_info_DC(PPRQINF03,PDEVICEINFO); 
create_print_DC(PDEVICEINFO); 
cneate_status_line(HWND); 
display_hint(SHORT); 
draw_page(HPS); 
draw_page_background(HPS); 

enum_print_queues(HWND,HWND,PULONG,PULONG,PULONG); 

free_info_DCs(PDEVICEINFO,ULONG); 

get_Job_properties(PPRQINF03,PDDINFO,ULONG); 

get_page_metrics(PDEVICEINFO); 

init_app(HWND); 

post_error(HWND,USHORT); 

process_print(HWND); 

process_size(MPARAM,MPARAM); 

process_command(HWND,MPARAM,MPARAM); 

query_device_info(HWND,PPRQINF03,PDEVICEINFO); 

query_form_info(HWND,PHCINFO); 


PRNT.RC 


/* 


Print Sample Resource File 
Chapter 11 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "prnt.h" 

#include "dialog.h" 

ICON ID_APPNAME PRNT.ICO 

RCINCLUDE PRNT.DLG 
RCINCLUDE ..\common\about.dig 

MENU ID_APPNAME 
BEGIN 

SUBMENU "-File", IDM_FILE 

BEGIN 

MENUITEM "Select Printer", IDM_CHOOSE_PRINTER 

MENUITEM "Print", IDM_PRINT 


A' 
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MENUITEM "Print in a Thread", 
MENUITEM SEPARATOR 
MENUITEM "About...", 

END 

SUBMENU "-Display", 

BEGIN 


IDM_PRINT_THREAD 

IDM_ABOUT 

IDM_DISPLAY 

IDM_DISP_BLANK, 0, MIA_CHECKED 

IDM_DISP_BOX 

IDM_DISP_ELLIPSE 

IDM PRINTER INFO 


MENUITEM "Blank page", 

MENUITEM "Box scaled to page", 
MENUITEM "Ellipse scaled to page 
MENUITEM SEPARATOR 
MENUITEM "Printer Information", 
END 

END 


STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 


ID_APPNAME 

"Sample Print Program" 

ID_NOQUEUE_ERROR 

"No Printers have been installed" 

ID_PRIORITY_HIGH 

"High" 

ID PRIORITY_DEF 

"Default" 

ID PRIORITY MIN 

"Low" 

ID_STATUS_HELD 

"Held" 

ID STATUS PEND 

"Pending Deletion" 

ID_STATUS_NORM 

"Released" 

ID_CAPS_CURRENT 

"Current" 

ID CAPS_SELECTABLE 

"Selectable" 

ID CAPS NONE 

"No Attribute Set" 

ID_TE CH_UN KNOWN 

"Unknown" 

ID_TECH_PLOTTER 

"Vector Plotter" 

ID_T ECH_RAST_DISP 

"Raster Display" 

ID_TECH_RAST_PRT 

"Raster Printer" 

ID_TECH_RAST_CAM 

"Raster Camera" 

ID_TECH_POSTSCRIPT 

"PostScript Device" 

ID_ERR_NODEF_PRINTERS 

"A printer has not been installed, or 
printers have been deleted." 

ID_ERR_FAIL_DEV_QUERY 

"A call to SplQueryDevice has failed" 

IDS_JOB__TITLE 

"RWP Sample print program" 

IDM_CHOOSE_PRINTER 

"Change the current printer" 

IDM_PRINT 

"Print to " 

IDM_PRINT_THREAD 

"Print in a separate thread to " 

IDM_ABOUT 

"Product information" 

IDM_DIS P_B LAN K 

"Display an empty page" 

IDM_DISP_BOX 

"Display a filled rectangle scaled to 


IDM_DISP_ELLIPSE 

IDM_DISP_X 

IDM PRINTER INFO 


page" 

"Display a filled ellipse scaled to the page 
"Display the ..." 

"Show information on all printers" 


END 




Threads and 
Semaphores 


Multitasking in OS/2 

OS/2 is a multitasking operating system. This means lines of execution or processing do 
not simply start and then proceed continuously until termination. Individual lines of 
execution do not have sole use of the central processor and other system resources. Many 
different programs can be active on the system simultaneously. 

Consider the common situation when an application, during its 
processing, is directed to output something to a printer. Print¬ 
ers are comparatively slow. If the application cannot continue 
its processing until the printer has completed outputting the 
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data, the user must wait. Further, if the operating system has no means to spool the data 
for later delivery to the printer, every process, every application, must wait. To circum¬ 
vent this, the central processor’s time and attention can be divided among the various 
processes making demands on it. This is called multitasking. 

Three Types of Multitasking 

Multitasking within OS/2 is of three different sorts: sessions, processes, and threads. When 
taken together, these three divisions of multitasking within OS/2 improve the speed, re¬ 
sponsiveness, and efficiency of the system. With a little thought, you can see the neces¬ 
sity for having these three different levels of multitasking. 

Sessions 

The highest level, one that will concern few programmers in OS/2, is the session. A ses¬ 
sion consists of one or more processes that have their own virtual console. The virtual 
console consists of a virtual screen and buffers for input from the keyboard and mouse. 
Sessions may be arranged in the familiar parent-child hierarchy. Sessions may start other 
sessions. Sessions may also end the processing of its child sessions, although it cannot 
end the processing of those sessions descendent from its children. 

Processes 

Within the session level is another level of multitasking. It is called the process. Each session 
contains at least one process, but it may contain many. It is convenient to think of an 
application as synonymous with the term process. A process is an application that has been 
loaded into memory and made ready for execution. Each process has a number of 
resources allocated for its use. These resources include memory, files, pipes, queues, 
semaphores, and others. Processes may create other processes. These too are arranged in 
a parent-child hierarchy. Child processes may inherit the resources owned by the parent 
process, except for memory. Child processes do not inherit the memory of their parent 
processes. Once again, the parent process may end the child process. 


Threads 

The lowest level of multitasking is called the thread. Different threads of execution within 
an application are what most programmers will be concerned with. Threads are lines of 
execution within a process. Each process has at least one thread, called the main thread. 
OS/2 creates this first thread for the application when it starts executing the process. To 
carry out tasks that are not related, other threads may be created by the process as it runs. 
For example, in the situation at the beginning of this chapter, the process could start another 
thread that sends data to the printer so that the main process may continue accepting in¬ 
put from the user. In this way, the application seems far more responsive to the user. 


054 
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Threads are composed of CPU register values, a stack, and instructions. Threads do 
not own resources individually. A thread shares resources with the process that created it 
and all the other threads within the process. Threads are not organized in the previously 
described parent-child relationship for the other levels of multitasking. With one excep¬ 
tion, all threads within a process are peers. For example, if one thread opens a file, that 
file is available to all the other threads. If one thread starts another thread which then 
opens a file, that file is still available to the thread that started it, as well as all the other 
threads. There is an exception to this peer relationship: Although the threads within a 
process are considered to be peers, if the first thread within a process ends, all other threads 
within that process also end. Threads may also suspend and resume the execution of other 
threads. This allows threads to coordinate access to time-critical resources. 

Creating a thread is much faster than creating a new process. This is because the pro¬ 
cess resources do not have to be allocated for a new thread, but do for a new process. In 
addition, OS/2 can switch between threads much faster than it can switch between pro¬ 
cesses. There is no task switching involved, just the activity of setting the thread’s CPU 
registers and current priority. 

Threads and Time Slices 

Because threads are the smallest unit of execution and time slices are the smallest unit of 
time parceled out for execution, these two are closely related. Time slices and threads are 
related by the concept of dispatch priority. Each thread is assigned a dispatching priority 
by the operating system. A thread’s dispatch priority governs how often and for what 
length of time a thread will have the use of the central processor. Access is rotated among 
threads after the passage of a certain interval of time. This interval is based on the time 
slice. 

Priority Classes and Priority Levels 

When a thread is created, it is given a priority classing, a priority level Four priority classes 
are within OS/2. These are—in order of priority—time critical, fixed high, regular, and 
idle-time. Within each of these classes, priority is further subdivided into priority levels. 
Each priority class has 32 priority levels within it. These are numbered from 0 to 31. 
Every thread marked time critical has a higher priority than those marked fixed high and 
so forth. Within each class, those with higher integer values for priority level are dispatched 
before those with lower values. For example, if two threads among several that are ex¬ 
ecuting on a system are marked time critical, these two will always receive a time slice 
before any other thread on the system. However, if one of these two time critical, threads 
has a priority level set at 25 while the other has a priority level of 10, the thread with 
priority level 25 will always be executed first unless it is blocked or suspended. 
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Threads marked time critical are executed immediately and continuously. These 
threads are generally those that handle events which must receive immediate attention, 
such as communication ports and real-time events. Fixed high threads receive a time slice 
when no time-critical threads are waiting. Regular threads, as the name implies, is the 
classification most threads within the system will have. These are dispatched on the basis 
of I/O activity, whether they are running in the foreground or background, and use of 
the processor. Threads with idle-time as their priority class receive time slices only when 
no other threads are waiting. 

Applications can change the priority of threads. This is recommended in situations when 
other threads are waiting on a particular thread to finish a task before they can continue. 
However, it is best to change the priority level among the threads of your application, 
rather than give one thread the highest priority class and level in the system. Because the 
processor’s time must be divided among all the applications and threads running on the 
system, gaming the system in this way would, in fact, degrade the overall performance. 

OS/2 System Settings for Threads 

OS/2 provides four settings related to threads that are configurable within the 
CONFIG.SYS file. These settings affect how the system allocates time slices and how it 
determines the priority of each thread. The maximum number of threads allowed in the 
system is controlled with the THREADS statement 

THREADS=n 

where n is the maximum number of threads (range 16..256). All threads begin with an 
initial priority setting. As time goes on and threads receive the CPU and more threads 
come into existence, some threads may receive more time slices than others. Some threads 
may also be involved in CPU intensive tasks that cause other threads to receive less and 
less CPU over time. OS/2 uses two schemes to monitor the priority of threads. 
ABSOLUTE priority means all threads within a priority class are assigned time slices based 
solely on their priority level. DYNAMIC priority means that the recent time slice history of 
each thread is used to adjust the priority of threads dynamically. Threads that have not 
received much CPU relative to other threads in the same class will have their priorities 
temporarily adjusted upward to more evenly distribute the average CPU time per thread. 
The scheme that will be used is defined by using the PRIORITY statement: 

PRIORITY^[ABSOLUTE | DYNAMIC] 

ABSOLUTE Priorities are not adjusted according to system 

load. 

OS/2 adjusts the priority so that the priority 
of threads within the same priority class do 
not hog the CPU (default). 


DYNAMIC 
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When DYNAMIC priority is specified, the MAXWAIT directive establishes the maximum 
amount of time a thread will wait for the CPU before OS/2 adjusts its priority upward: 

MAXWAIT=seconds 

The interval of a time slice is specified with the TIMESLICE directive. Both a normal 
and maximum time slice interval can be specified. If a thread reaches the end of its time 
slice and is preempted by the system, its next time slice will be one tick longer as long 
as it has not reached the maximum time slice interval. Both values are specified in 
milliseconds: 

TIMESLICE=x[j y] 

x = Normal length of a time slice before a thread gives up 

the CPU (minimum of 32). 

y = Maximum length of a time slice (minimum of 32 and 

maximum of 65536). 

Working with Threads 

OS/2 provides a number of functions for working with threads. These enable you to 
perform tasks such as creating a thread, obtaining information on a thread, terminating 
a thread, and so forth. 

DosCreateThread is used to create a new thread of execution. The new thread is 
created as an asynchronous thread and has access to all resources of the process in which 
it is executing. The initial priority of the new thread is the same as the thread making the 
DosCreateThread call. The format of DosCreateThread is as follows: 

APIRET APIENTRY DosCreateThread(PTID ptid, PFNTHREAD pfn, ULONG param, 
ULONG flag, ULONG cbStack). 


PTID 

ptid 

Address of a TID variable to receive a 
new thread identifier. 

PFNTHREAD 

pfn 

Initial entry point of the thread. 

ULONG 

param 

Single parameter passed to the initial 
thread function. 

ULONG 

flag 

Flags setting the initial state of the 
thread: 

0x00000001 Create thread in a 

suspended state. 

0x00000002 Precommit all pages 

in the thread’s stack. 
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The default settings cause the thread to 
start immediately upon creation and to 
use the default method for committing 
the pages of the stack. 

ULONG cbStack Size of the thread’s stack. Minimum of 

8K is used by OS/2. 

A new thread is created, and the function specified by the pf n parameter is the initial 
point of execution. A single parameter can be passed to the thread. If more than one 
parameter is required, this should be the address of a structure containing the data. Nor¬ 
mally, a thread starts immediately upon creation. If you need to perform some additional 
setup or simply want the thread to wait until a particular event occurs, you can create the 
thread in a suspended state by setting the low bit of the flag parameter. The thread func¬ 
tion is prototyped as follows: 

typedef VOID (*PFNTHREAD)(VOID); 

It, however, actually can have one parameter defined for it. For example, to create a new 
thread whose initial entry point is the function ThermometerThread, the following call 
can be used: 

VOID ThermometerThread (HWND); 

TID ThreadID; 

HWND hWndClient; 

DosCreateThread (&ThreadID, (PFNTHREAD)ThermometerThread, 

(ULONG)hWndClient, 0, 0x5000); 

ThermometerThread takes one parameter, which is the handle to a client window. 
The thread created in this example has a stack size of 20K. Remember, while 
ThermometerThread is the initial entry point, the new thread can call any function within 
the process. It is also important to be sure that the parameter passed to the thread func¬ 
tion is not passed in a register. For example, using the IBM C/Set compiler, this could be 
specified with the linkage program: 

#pragma linkage (ThermometerThread,system) 

A thread can terminate in several ways. The thread can terminate naturally by re¬ 
turning from the initial thread function or by calling Dos Exit. It will also terminate when 
DosKillThread is called with the thread’s identifier or when thread 1 terminates. Nor¬ 
mally, a thread will terminate itself by completing its processing and calling DosExit. 
The call to DosExit can also terminate the entire process, but this is not the normal case: 

VOID APIENTRY DosExit(ULONG action, ULONG result); 
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ULONG ulAction Specifies entity to terminate: 

EXIT_THREAD Current thread is 

terminated. 

EXIT_PROCESS Current process is 

terminated, including 
all threads. 

ULONG result Result code passed to any thread waiting for the 

process to terminate. 

A thread may also decide to terminate itself when it receives a signal from another 
thread to terminate or when an error condition occurs. In any case, the call to DosExit 
for a thread normally appears as follows: 

DosExit (EXIT_THREAD, 0L); 

If thread 1 issues the call to DosExit, the entire process is terminated. A thread can 
also kill another thread with the DosKillThread function 

APIRET APIENTRY DosKillThread(TID tid); 

where TID tid is the thread identifier to kill. 

It is not possible for a thread to kill itself with this function. If the thread identifier 
is 1, the entire process is terminated. 

Now that you have looked at how to create and terminate a thread, look at how to 
control a thread while it is executing. Associated with every process is a Process Informa¬ 
tion Block. In addition, every thread has an associated Thread Information Block. As 
you might expect, these blocks contain information related to the current state of both 
the process and the individual thread. A thread can retrieve this information by calling 
DosGetlnfoBlocks: 

APIRET APIENTRY DosGetlnfoBlocks(PTIB *pptib,PPIB *pppib); 


PTIB 

*pptib 

Address of a PTIB pointer to receive the address 
of the Process Information Block (PIB). 

PPIB 

*p pp ib 

Address of a PPIB pointer to receive the address 
of the Thread Information Block (TIB). 


For example, a thread can retrieve this information with the following call: 

PPIB ppib; 

PTIB ptib; 

DosGetlnfoBlocks (&ptib, &ppib); 

The DosGetlnf oBlocks function is discussed in detail in Chapter 15, “Miscellaneous 
Topics.” 
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We discussed earlier the mechanism by which OS/2 determines which thread to ex¬ 
ecute. Threads with a priority class of time critical are executed before those of fixed high. 
Fixed high threads are executed before regular, and those are executed before idle-time 
threads. Within each class, a thread has a priority from 0 to 31. Higher priority threads 
within the same class obviously execute before those of a lower priority. This priority order 
is shown here: 


Time Critical 

31 


30 


0 

Fixed High 

31 

30 


0 

Regular 

31 

30 


0 

Idle-Time 

31 


30 


0 


When a thread of higher priority is ready to execute, OS/2 will preempt any lower 
priority thread currently executing and allow the higher priority thread to execute. This 
occurs even if the lower priority thread has not completed its time slice. Threads of the 
same priority are allocated time slices in a round-robin scheme. Thread priorities can be 
changed with the DosSetPriority function. DosSetPriority allows any thread in a 
process to change the priority of any other thread in the process. It also allows a thread to 
change the priority of any thread in another process as long as the other thread’s priority 
has not been changed from the default priority level: 

APIRET APIENTRY DosSetPriority(ULONG scope, ULONG class, LONG delta, 

ULONG ultid); 


ULONG 


scope 


Scope of the priority change: 


PRTYS_PROCESS 

PRTYS_PROCESSTREE 

PRTYS_THREAD 


All immediate threads 
of a process. 

All threads and descen¬ 
dants of either the 
current process or a 
child process. 

An individual thread. 
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Priority class of the thread: 

PRTYC_NOCHANGE No change to priority 

class. 

PRTYCJDLETIME Idle-time priority class. 

PRTYC_REGULAR Regular priority class. 

PRTYC_TIMECRITICAL Time-critical priority 

class. 

Change to the priority: 

If PRTYC_NOCHANGE is specified for class, this is 
the relative change to the current priority. Valid 
values range from PRTYD_MINIMUM to 
PRTYD_MAXIMUM (—31 to 31). For all other class 
specifications, this is the absolute priority level within 
the class. 

Process or thread identifier: 

If a scope of PRTYC_PROCESS or 
PRTYC.PROCESSTREE is specified, this is a 
process identifier. For a scope of PRTYS_THREAD, 
this is a thread identifier. Zero indicates the current 
process or thread. 

The following examples use the DosSetPriority function to set the priority of a 
thread to idle-time: 

DosSetPriority (PRTYS_THREAD, PRTYC_IDLETIME, 0, StatusThreaclID); 
to time critical with a priority level of 10: 

DosSetPriority (PRTYS_THREAD, PRTYC_TIMECRITICAL, 10L, StatusThreadID) 

and to increase the priority level of the current class by 1: 

DosSetPriority (PRTYS_THREAD, PRTYC_NOCHANGE, 1L, 0L); 

Typically, the priority of a thread is increased when the thread is performing some 
activity that needs to be completed before another thread can continue. For example, 
suppose one thread is recalculating the cells of a spreadsheet, and another thread is 
attempting to display a graph of the new data but is waiting for the calculations to 
complete. The graph thread may increase the priority of the calculation thread so 
that the calculation thread receives most of the CPU time for the process, which allows 
the calculation thread to complete much faster. 


ULONG class 


LONG delta 


ULONG ultid 
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Another mechanism used in controlling the execution of a thread is to temporarily 
suspend its execution. Suppose you have a thread that is searching the files on a disk for 
a text string. If another thread needs to save data to a file, it can temporarily suspend the 
search thread while writing the data to the disk. When the data has been saved to disk, it 
can resume the search thread. A thread can be suspended by calling DosSuspendThread, 
and it subsequently can be resumed by calling DosResumeThread. These two functions 
are described here: 

APIRET APIENTRY DosSuspendThread(TID tid); 

TID tid Thread identifier to suspend execution. 

APIRET APIENTRY DosResumeThread(TID tid); 

TID tid Thread identifier to resume execution. 

Notice that it is possible to suspend and resume threads only within the scope of a 
process. It is not possible to suspend or resume threads belonging to another process. 

To suspend a thread, you can issue the following call: 

DosSuspendThread (ThreadID); 

To resume it, issue the following call: 

DosResumeThread (ThreadID); 

A thread can also suspend itself for a specified amount of time by using the DosSleep 
function: 

APIRET APIENTRY DosSleep(ULONG msec); 

ULONG msec Number of milliseconds to suspend the current thread. 

When DosSleep is called, the thread immediately relinquishes any remaining CPU 
time in its current time slice and suspends itself for approximately the amount of time 
specified. DosSleep can be used, for example, in a thread that is constantly displaying 
the status of the communications line. In this case, the thread will query and display the 
current line status and call DosSleep for a small amount of time, repeating this process 
until the thread is terminated. An example of this type of thread is shown in Chapter 14, 
“Communications Basics.” 

While a thread is suspended, it receives no CPU time regardless of that thread’s pri¬ 
ority class or priority level. This might create a problem if a thread containing a mes¬ 
sage queue is suspended. This problem is discussed in a later section about threading 
considerations. 
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Because all threads within a process share the data segment and resources of the pro¬ 
cess, you can foresee problems where two threads attempt to update the same data item 
or to use the same resource at once. The classic example is one of incrementing a counter. 
Look at the assembler code generated for the following statements: 

ulCount++; 

You might see an unoptimized sequence of instructions: 

MOV EAX,[02BC] 

INC EAX 

MOV [02BC],EAX 

Suppose you have two threads with each executing the instruction ulCount++ at the 
same time. If the first thread executes the first two assembler instructions and then is 
preempted by the system, and thread 2 executes all three assembler instructions and is 
preempted so that thread 2 can continue, ulCount will contain an incorrect value: 


Thread 1 Thread 2 ulCount 

T MOV EAX,[02BC] 0 

i INC EAX 0 

m MOV EAX,[02BC] 0 

e INC EAX 0 

MOV [02BC],EAX 1 

| MOV [02BC],EAX 1 


V 

Notice that the final value of ulCount is 1, even though it was incremented twice 
and should contain the value 2. This is a basic example of the kind of problems that may 
arise with shared data. If a file handle is being shared and multiple threads are position¬ 
ing the file pointer and reading or writing the file, there are more areas where contention 
might occur. One option is to suspend the other thread whenever a shared data item 
or resource is being updated and to resume it when completed. This, however, can be 
involved when multiple threads are being used. 

A much more effective method is to protect shared data and resources with a critical 
section. While a thread is executing within a critical section, all other threads in the pro¬ 
cess are temporarily suspended. This way, the calling thread has exclusive access to the 
CPU for that process without being concerned about another thread in the current pro¬ 
cess interrupting it. Critical sections should be short and quick because you are suspend¬ 
ing all other threads. 

A critical section is entered with a call to DosEnterCritSec and exited with a call to 
DosExitCritSec. These functions appear as shown here: 

APIRET APIENTRY DosEnterCritSec(VOID); 
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APIRET APIENTRY DosExitCritSec(VOID); 

Using our example, you enclose the counter increment within a critical section as 
follows: 

DosEnterCritSec(); 
ulCount++; 

DosExitCritSec(); 

It is possible to nest critical sections. This can be done only by the thread that is ex¬ 
ecuting within a critical section. A matching DosExitCritSec must be made for each 
DosEnterCritSec before other threads in the current process are allowed to continue 
executing. 

An additional factor for declaring variables that will be shared among multiple threads 
is to ensure that the variable is not stored in a register. Because each thread has its own set 
of registers, this type of variable could not be shared. Use the volatile attribute if it is possible 
for the variable to be defined in a register. 

The last thread API enables you to either wait for another thread to terminate or to 
check if another thread is still executing. DosWaitThread enables you to check the status 
of another thread: 

APIRET APIENTRY DosWaitThread(PTID ptid, ULONG option); 

PTID ptid Address of TID variable. On input, the thread ID 

(identification) specifies the thread to query. If the 
thread ID is zero, the next thread in the process to 
terminate is used. Upon return, the thread ID 
contains the ID of the thread that has terminated. 
ULONG option Wait option: 

DCWW_WAIT Do not return until the 

indicated thread has 
terminated. 

DCWW_NOWAIT Return immediately 

with the status of the 
indicated thread. 

The return code from this function indicates the status of the queried thread: 

NO ERROR The thread has terminated 

(DCWW_WAIT). 

ERROR_THREAD_NOT_TERMINATED The thread has not termi¬ 

nated yet. 

ERROR_INVALID_THREADID An invalid thread ID 

was specified. 
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Suppose a thread is searching the disk for a file, and in another thread, the user presses 
a button to perform some action on that file. Because the second thread must wait for 
the search thread to complete, it could issue the following request: 

if (IDosWaitThread (&SearchThread, DCWW_WAIT)) 

/* continue */ 

If the search thread has terminated by the time this call is made, the call will return 
immediately; otherwise, it will not return until the SearchThread terminates., 

The Thread Function 

The function specified in the DosCreateThread call is the initial entry point of the thread. 
If a thread creates a message queue, that thread is considered a message queue thread; 
otherwise, it is a nonmessage queue thread. A message queue is required for any thread 
that must either create windows, send messages to other windows, or call functions that 
result in messages being sent to other windows. An application usually creates at least 
one message queue thread, the main thread. A thread becomes a message queue thread 
by calling WinCreateMsgQueue. Windows created in one message queue thread cannot 
be deleted by another message queue thread. 

Nonmessage queue threads do not have a message queue to worry about, so they do 
not have to call WinPeekMsg or WinGetMsg to retrieve messages from the queue. These 
threads can concentrate solely on performing the thread’s task. Although nonmessage 
queue threads cannot create windows or cause messages to be sent to other windows, they 
can post messages to other windows. 

Threading Considerations 

When you design your threads and the operations to be performed in each, there are several 
areas of concern to keep in mind. These threading considerations are necessary to pro¬ 
vide a well behaved thread that does not degrade overall system performance, or even 
cause your process to stop functioning. 

Here are some general rules of thumb for creating threads: 

# Do not assume any timing related dependencies. 

A thread should not assume that another thread in the process will be executing 
a portion of code at any particular time. In other words, do not assume that 
another thread isn’t modifying shared data that the current thread is manipulat¬ 
ing. Threads should protect all shared data by either suspending competing 
threads, enclosing the code sequence in a critical section, or using semaphores. 
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# Do not suspend message queue threads. 

If a message queue thread must be suspended, it should be suspended only for 
a short time. This includes using critical sections in a message queue thread. 
While a message queue thread is suspended, it is unable to process messages 
sent to it. This includes messages sent while focus is changing (for example, 
WM_QUERYFOCUSCHAIN) or when the mouse is moved over a window created by 
the suspended thread (for example, WM_HITTEST). If the current focus window 
belongs to a thread that is suspended, when another thread attempts to obtain 
the focus, it will be unable to do so. This is because the thread attempting to 
gain the focus will be blocked while the WM_QUERYFOCUSCHAIN message is being 
sent by the system to the suspended thread. 

® Be a good neighbor when it comes to changing thread priorities. 

Increases in thread priority should be done only on a temporary basis. If a 
nonmessage queue thread’s priority is raised and it is a compute intensive 
thread, other threads with lower priority will not receive any CPU time. As long 
as the higher priority thread is in the ready state, it will starve out lower priority 
threads. This also goes for message queue threads that use WinPeekMsg loops 
and raise their priority above other threads. Even when there are no messages in 
the higher priority thread’s message queue, the thread is continuously in a loop 
calling WinPeekMsg and is always in the ready state; therefore, it will receive the 
CPU before a lower priority thread. Because there may be other threads of lower 
priority executing somewhere in the system, it is a good idea to insert a call to 
DosSleep somewhere in a WinPeekMsg loop. Using a small sleep interval of 5 to 
10 milliseconds is usually enough to give, at least, some time to lower priority 
threads. 

Semaphores 

For processes or threads to coordinate their activities, some means of communication 
among them is necessary. This is accomplished with something termed “interprocess 
communication.” OS/2 allows three different types of interprocess communication. They 
are pipes, queues, and semaphores. Pipes are buffers used to pass data between processes. 
Queues are ordered lists of elements to which more than one process may add an ele¬ 
ment. Semaphores are flags or signals maintained by the operating system. Semaphores 
allow processes to signal the start and finish of operations. They also permit the mutually 
exclusive ownership of resources by individual threads. 

Semaphores are created and maintained in memory buffers by OS/2. Because a sema¬ 
phore is always resident in memory, setting and clearing semaphores occurs rapidly. 
Threads use semaphores by setting or clearing a semaphore or by waiting for a semaphore 
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to be set or released by another thread. While a thread is waiting for a semaphore, only 
the waiting thread is blocked. Other threads are allowed to continue executing. Using a 
semaphore is a more effective way of protecting access to a resource than is using a criti¬ 
cal section. Remember, when DosEnterCritSec is used, all other threads in the process 
are suspended until the DosExitCritSec is called. In most cases, a resource is not shared 
among all threads of a process, so using a critical section needlessly stops nonconflicting 
threads from executing—which is not wise to do in so arbitrary a way. Further, a critical 
section cannot be used to protect a resource shared among processes, whereas a sema¬ 
phore can. 

OS/2 maintains three types of semaphores. These are event semaphores, mutual exclu¬ 
sion semaphores , and multiple wait semaphores. Event semaphores allow threads to signal 
other threads that a particular event has transpired. Mutual exclusion semaphores let 
threads cooperate in their access to resources. Essentially, a mutual exclusion semaphore 
allows threads to solely own a resource for a period so that threads can serialize their ac¬ 
cess to the resource. Multiple wait semaphores can be used in two ways. They allow threads 
to wait for a collection of resources to become available or for several events to occur. A 
flag may also be set for this type of semaphore, which allows the process to continue if 
any one of the events occurs or any one of the resources becomes available. 

Semaphores may be private or shared. A private semaphore is available to all threads 
of a process. Shared semaphores are available for use by multiple processes. Semaphores 
are accessed by a handle assigned when the semaphore is created. Private semaphore handles 
are known by all threads of a particular process. Shared semaphore handles can be ob¬ 
tained by a process in two ways. The handle can be communicated to a process through 
a message, queue, or pipe, or even defined in the global data area of a DLL. A semaphore 
can also be given a name, and any process knowing its name can open it. Semaphores 
without names are called “anonymous semaphores.” Semaphores with names are called 
“named semaphores.” Semaphore names must conform to file system naming conven¬ 
tions and contain the prefix \SEM32\. For example, a legal semaphore name is 
\SEM32\RCVQUEUE. All named semaphores are considered shared. It is possible for 
two processes to attempt to create a named semaphore with the same name. In that case, 
the second attempt to create a semaphore with the same name will fail. 

Each process sharing a semaphore must explicitly gain access to the shared semaphore 
by opening it. The process that initially creates the semaphore implicitly opens the sema¬ 
phore. Ail other processes must issue a request to open it. When a process is done with a 
semaphore, it should close it. OS/2 maintains a count of the number of times a sema¬ 
phore has been opened. This count is decremented each time the semaphore is closed. 
The semaphore is deleted when the count becomes zero. A thread may nest calls to open 
a semaphore, but must close it an equal number of times. 
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When a thread calls to wait for exclusive use of a semaphore or to wait for a sema¬ 
phore event to be signalled, it specifies an amount of time to wait. If the specified time 
passes without gaining access to the semaphore or the event being posted, the semaphore 
request will time out. Wait times are specified as milliseconds, SEM_INDEFINITE_WAIT, 
or SEM_IMMEDIATE_RETURN. The return code from the semaphore request will indicate 
whether the request was satisfied or timed out. 

Event Semaphores 

Event semaphores signal that an event has occurred. An event semaphore will be in one 
of two states. These two states are reset and posted. If an event semaphore is in the reset 
state, this conventionally means that the desired event has not occurred. The operating 
system, therefore, blocks threads and processes that are waiting on that semaphore. Blocked 
means execution for the thread is suspended. The threads waiting on the event cease ac¬ 
tivity until the semaphore changes to the posted state. When the semaphore is posted, all 
threads that were blocked on that thread, waiting for the event to occur, resume their 
execution. 

Examples of when to use an event semaphore include giving another thread the fol¬ 
lowing information: 

$ A file has been closed and is available for printing. 

@ A posted message has been processed. 

9 A file search has completed. 

# A thread is about to terminate. 

DosCreateEventSem is used to create a new event semaphore. An event semaphore’s 
initial state (posted or reset) is specified in this call: 

APIRET APIENTRY DosCreateEventSem (PSZ pszName, PHEV phev, ULONG flAttr, 
BOOL fState); 


PSZ 

PHEV 

ULONG 

pszName 

phev 

flAttr 

Name of the semaphore or NULL (anonymous) 
Address of event semaphore handle. 

Semaphore attribute (ignored if pszName is 
NULL). 



DC_SEM_SHARED Shared semaphore. 

BOOL 

fState 

Initial semaphore state: 



TRUE Semaphore is posted. 

EALSE Semaphore is reset. 
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The following call illustrates the creation of an anonymous shared event semaphore 
with an initial state of reset: 

HEV hevEvent; 

DosCreateEventSem (NULL, &hevEvent, DC_SEM_SHARED, FALSE); 

The process of creating an event semaphore also has implicitly opened it. Other pro¬ 
cesses can open an event semaphore with the DosOpenEventSem function: 

APIRET APIENTRY DosOpenEventSem (PSZ pszName, PHEV phev); 

PSZ pszName Name of the semaphore or NULL (anony¬ 

mous). 

PHEV phev Address of event semaphore handle. 

If pszName is NULL: 

The event semaphore handle referenced by 
phev must be the handle of an existing anony¬ 
mous semaphore. 

If pszName is not NULL: 

On input the event semaphore handle must be 
NULL; on output the event semaphore handle 
is updated with the semaphore handle. 

The following call opens the semaphore created in the previous example: 

DosOpenEventSem (NULL, &hevEvent); 

When a process is done with a semaphore, it calls DosCloseEventSem: 

APIRET APIENTRY DosCloseEventSem (HEV hev); 

HEV hev Handle of the event semaphore. 

The following call closes our semaphore: 

DosCloseEventSem (hevEvent); 

An event semaphore is reset to indicate the event has not occurred yet. While an event 
semaphore is in the reset state, all threads requesting the event semaphore will be blocked 
until it is posted. DosResetEventSem is used to reset the semaphore: 

APIRET APIENTRY DosResetEventSem (HEV hev, PULONG pulPostCt); 

HEV hev Handle of the event semaphore. 

PULONG pulPostCnt Address of variable to receive the post count. 
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The post count is the number of times DosPostEventSem has been called since 
DosResetEventSem was last called. If the semaphore is already in the reset state when 
this function is called, the return code will be ERROR_ALREADY_RESET: 

ULONG ulPostCount; 

DosResetEventSem (hevEvent, &ulPostCount); 

A thread signals an event by posting the event with DosPostEventSem: 

APIRET APIENTRY DosPostEventSem (HEV hev); 

HEV hev Handle of the event semaphore. 

This call increments the post count of the semaphore. Threads waiting on the sema¬ 
phore are unblocked and can continue executing: 

DosPostEventSem (hevEvent); 

When a thread needs to wait for an event to occur it uses the DosWaitEventSem func¬ 
tion. In specifying that it wants to wait for an event to occur, it can also indicate a time 
period to wait before continuing. If after the specified time period, the event has not 
occurred, the function returns ERROR_TIMEOUT. 

APIRET APIENTRY DosWaitEventSem (HEV hev, ULONG ulTimeout); 

HEV hev Handle of the event semaphore. 

ULONG ulTimeout Maximum time period to wait for the sema¬ 

phore (milliseconds). 

It can also be one of the following values: 

SEM_IMMEDIATE_RETURN Zero timeout 

period. 

SEM_INDEFINITE_WAIT No timeout 

period. 

If you want to wait indefinitely for your semaphore to be posted, use the following 

call: 

DosWaitEventSem (hevEvent, SEM_INDEFINITE_WAIT); 

Finally, a thread can query the current post count for an event semaphore at any time. 
Remember that the post count is the number of times DosPostEventSem has been called 
since DosResetEventSem was last called: 

APIRET APIENTRY DosQueryEventSem (HEV hev, PULONG pulPostCt); 

HEV hev Handle of the event semaphore. 

PULONG pulPostCnt Address of variable to receive the post count. 
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You can query the event semaphore with the following call: 
ULONG ulPostCount; 

DosQueryEventSem (hevEvent, &ulPostCount); 


Mutual Exclusion Semaphores 

Mutual exclusion semaphores prevent the simultaneous access of protected resources by 
different threads or processes. These semaphores are often referred to as “mutex” sema¬ 
phores. A thread makes a request of the semaphore when getting ready to access a pro¬ 
tected resource. If no other thread currently owns the semaphore, the request is granted, 
and the thread becomes the owner. On the other hand, if the semaphore is currently 
owned, the requesting thread is blocked. When done with the protected resource, the 
owning thread releases the semaphore. If there are outstanding requests for the semaphore, 
it is given to the blocked thread with the highest priority. If two blocked threads have the 
same priority, the request is satisfied in an FIFO order. 

Examples of when to use a mutual exclusion semaphore include the following: 

# Protecting write access to the same file handle. 

# Protecting updates to a shared memory object. 

# Protecting updates to a linked-list data structure. 


DosCreateMutexSem is used to create a new mutex semaphore. A mutex semaphore’s 
initial state (owned or unowned) is specified in this call: 

APIRET APIENTRY DosCreateMutexSem (PSZ pszName, PHMTX phmtx, 

ULONG flAttr, BOOL fState); 


Name of the semaphore or NULL (anonymous) 
Address of mutex semaphore handle. 

Semaphore attribute (ignored if pszName is 


PSZ pszName 

HMTX phmtx 

ULONG flAttr 


BOOL fState 


NULL). 

DC_SEM_SHARED 

Initial semaphore state: 

TRUE 

FALSE 


Shared semaphore. 

Semaphore is owned. 
Semaphore is 
unowned. 


The following call illustrates the creation of a named shared mutex semaphore with 
an initial state of unowned: 
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HMTX hmtxShared; 

DosCreateMutexSem ( 11 \ \SEM32\ \DEMO M , &hmtxShared, DC_SEM_SHARED, 

FALSE); 

The process creating a mutex semaphore also has implicitly opened it. Other pro¬ 
cesses can open a mutex semaphore with the DosOpenMutexSem function. 

DosOpenMutexSem (PSZ pszName, PHMTX phmtx); 

pszName Name of the semaphore or NULL (anonymous), 
phmtx Address of mutex semaphore handle. 
pszName is NULL: 

The mutex semaphore handle referenced must 
be the handle of an existing anonymous sema¬ 
phore. 

pszName is not NULL: 

On input, the mutex semaphore handle must 
be NULL. On output, the mutex semaphore 
handle is updated with the semaphore handle. 

The following call is used by another process to open the semaphore created in the 
previous example: 

HMTX hmtxShared = (HMTX)NULL; 

DosOpenMutexSem (" WSEM32WDEM0", &hmtxShared); 

When a process is done with a semaphore, it calls DosCloseMutexSem. 

APIRET APIENTRY DosCloseMutexSem (HMTX hmtx); 

HMTX hmtx Handle of the mutex semaphore. 

The following call closes our semaphore: 

DosCloseMutexSem (hmtxShared); 

A mutex semaphore is used to protect access to a shared resource. A thread should 
obtain ownership of a mutex semaphore before proceeding to use the shared resource. 
Ownership is requested with the DosRequestMutexSem function. If the semaphore is 
currently owned, the thread is blocked until either the semaphore is released by the cur¬ 
rent owner and the thread is granted ownership or the timeout period expires. In requesting 
ownership of the mutex semaphore, the thread also specifies a time period to wait before 
continuing. If after the specified time period the semaphore request is not granted, the 
function returns ERROR TIMEOUT: 


APIRET APIENTRY 
PSZ 

PHMTX 
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APIRET APIENTRY DosRequestMutexSem (HMTX hmtx, ULONG ulTimeout); 

HMTX hmtx Handle of the mutex semaphore. 

ULONG ulTimeout Maximum time period to wait for the semaphore 

(milliseconds). 

It can also be one of the following values: 

SEM_IMMEDIATE_RETURN Zero 

timeout 

period. 

SEM_INDEFINITE_WAIT No 

timeout 

period. 

The following call requests the mutex semaphore with a 10 second timeout: 
APIRET RetCode; 

RetCode = DosRequestMutexSem (hmtxShared, 10000L); 

OS/2 keeps a count of the number of times DosRequestMutexSem is called for each 
mutex semaphore. This internal count is decremented each time the semaphore is 
released with a call to DosReleaseMutexSem. A thread may nest calls to 
DosRequestMutexSem, but must call DosReleaseMutexSem an equal number of times. 

A thread releases a mutex semaphore by calling DosReleaseMutexSem: 

APIRET APIENTRY DosReleaseMutexSem (HMTX hmtx); 

HMTX hmtx Handle of the mutex semaphore. 

If the request count for the semaphore becomes zero after this call, the thread with 
the highest priority that is waiting on a DosRequestMutexSem call for this semaphore is 
unblocked and allowed to execute. 

To release ownership of our mutex semaphore, the following call is used: 
DosReleaseMutexSem (hmtxShared); 

At any point, a thread can query the mutex semaphore to determine who the cur¬ 
rent owner is and the number of DosRequestMutexSem calls without a matching 
DosReleaseMutexSem call: 

APIRET APIENTRY DosQueryMutexSem (HMTX hmtx, PPID ppid, PTID ptid, 
PULONG pulCount); 


HMTX 

hmtx 

Handle of the mutex semaphore. 

PPID 

ppid 

Address of variable to receive process ID 



of semaphore owner. 

PTID 

ptid 

Address of variable to receive thread ID 



of semaphore owner. 
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PULONG pulCount Address of variable to receive request count. 

If the semaphore is currently unowned, the request count will be zero. You can query 
the mutex semaphore with the following code: 

PID pid; 

TID tid; 

ULONG ulRequestCount; 

DosQueryMutexSem (hmtxShared, &pid, &tid, &ulRequestCount); 

Multiple Wait Semaphores 

Multiple wait semaphores allow a process or thread to wait on several events to occur 
before proceeding. They can also be used to cause the thread or process to wait for several 
different resources to become available before proceeding. Multiple wait semaphores are 
often referred to as “muxwait” semaphores. Muxwait semaphores are lists of other event 
or mutex semaphores. These lists can be up to 64 entries in length consisting of either 
mutex or event semaphores. The two different types cannot be mixed in the same list. If 
a shared muxwait semaphore is created, all semaphores contained in the muxwait sema¬ 
phore must be shared semaphores. Private mutex semaphores can mix both private and 
shared versions of the same semaphore type. 

When muxwait semaphores are created, they can be flagged to operate in one of two 
ways. In the first case, if the muxwait semaphore consists of a list of events, threads will 
wait until all the semaphores have been posted. Similarly, if the muxwait semaphore 
consists of a list of mutex semaphores, threads will wait until all the mutex semaphores 
have been released before continuing. In the second way of operating, if the muxwait 
semaphore consists of a list of events, threads wait for any one of the event semaphores to 
be posted before continuing. If the muxwait semaphore consists of mutex semaphores, 
threads will wait until any one of the mutex semaphores has been released. 

It is important to note at this point that just because a semaphore is contained within 
a muxwait semaphore, it does not change the use of that semaphore. In addition, a sema¬ 
phore can be contained within multiple muxwait semaphores. 

Here are examples of when to use a multiple wait semaphore: 

• When requesting access to two or more shared memory objects where each 
shared memory object is protected by a mutex semaphore. 

© When attempting to update multiple tables in a database where each table is 
protected by a mutex semaphore. 

• When waiting for two calculation threads to complete, each signaling their 
completion by posting an event semaphore. 
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Before creating a muxwait semaphore, all semaphores to be contained in it must be 
created and opened. All the semaphores are then added to an array of SEMRECORD struc¬ 
tures. The SEMRECORD structure contains two fields: 

typedef struct 

{ 

HSEM hsemCur; 

Handle of the semaphore (either event or mutex) 

ULONG ulUser; 

User-defined value 

} SEMRECORD; 

The ulUser field is defined solely for the application to identify the semaphore. This 
value is returned when a muxwait semaphore request is satisfied. A muxwait semaphore 
can contain at most 64 event or mutex semaphores. Assume you want to create a private 
muxwait semaphore made up of one shared mutex semaphore and one private mutex 
semaphore. You would create the semaphores and put the information in a SEMRECORD 
array: 

SEMRECORD SemRecords[2]; 

DosCreateMutexSem ("\\SEM32\\DEM0", &SemRecords[0].hsemCur, 
DC_SEM_SHARED, FALSE); 

SemRecords[0].ulUser = 0; 

DosCreateMutexSem (NULL, &SemRecords[1].hsemCur, 0, FALSE); 
SemRecords[0].ulUser = 1; 

With the array SemRecords defined, the muxwait semaphore can be created with the 
DosCreateMuxWaitSem function: 

APIRET APIENTRY DosCreateMuxWaitSem (PSZ pszName, PHMUX phmux, 

ULONG cSemRec, PSEMRECORD pSemRec, ULONG flAttr); 


PSZ 

pszName 

Name of the semaphore or NULL 
(anonymous). 

PHMUX 

phmux 

Address of muxwait semaphore handle. 

ULONG 

cSemRec 

Number of semaphores contained in the 
array. 

PSEMRECORD 

pSemRec 

Address of array of SEMRECORD 
structures defining the semaphores. 

ULONG 

flAttr 

Semaphore attribute: 

DC_SEM_SHARED Shared 

semaphore 
(ignored if 
pszName is 
NULL). 
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DCMW_WAITJ\NY Semaphore 
request is 
satisfied when 
any one of the 
semaphores is 
either posted 
or released. 

DCMW_WAIT_ALL Semaphore 
request is 
satisfied only 
when all 
semaphores are 
either posted 
or released. 

Using the array of two semaphores defined previously, you can now create a private 
muxwait semaphore that must have both semaphores to satisfy the request: 

HMUX hmuxPrivateAll; 

DosCreateMuxWaitSem (NULL, &hmuxPrivateAll, 2L, SemRecords, 
DCMW_WAIT_ANY); 

The process creating a muxwait semaphore also has implicitly opened it. Other pro¬ 
cesses can open a muxwait semaphore with the DosOpenMuxWaitSem function. Remem¬ 
ber that to successfully open a muxwait semaphore, a process must have individually 
opened each semaphore contained in the muxwait semaphore. Opening a muxwait sema¬ 
phore does not automatically do this for a process: 

APIRET APIENTRY DosOpenMuxWaitSem (PSZ pszName, PHMUX phmux); 

PSZ pszName Name of the semaphore or NULL (anonymous). 

PHMUX phmux Address of muxwait semaphore handle. 

If a process creates a shared muxwait semaphore named \SEM32\MUXSHARE, 
another process can open it with the following call: 

HMUX hmuxShare; 

DosOpenMuxWaitSem ("\\SEM32\\MUXSHARE", &hmuxShare); 

When a process is done with a muxwait semaphore, it calls DosCloseMuxWaitSem. 
APIRET APIENTRY DosCloseMuxWaitSem (HMUX hmux); 

HMUX hmux Handle of the muxwait semaphore. 

The following call closes the shared semaphore previously opened: 
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DosCloseMuxWaitSem (hmuxShare); 

Things get a little more complicted when a thread decides to wait or request a muxwait 
semaphore. First look at how a muxwait event semaphore operates. A thread waiting on 
a muxwait event semaphore will be triggered to continue execution in one of two ways 
depending on the wait attribute specified when the semaphore was created: 

DCMW_WAIT_ANY The muxwait semaphore request is triggered 

when any one of the event semaphores is 
posted. 

DCMW_WAIT_ALL The muxwait semaphore request is triggered 

when all the event semaphores are in the 
posted state at the same time. If any one of 
the event semaphores is in the reset state, the 
request is not triggered. 

For a thread requesting a muxwait mutex semaphore, the thread will be blocked until 
the semaphore(s) is released. This will depend on the wait attribute specified when the 
semaphore was created: 

D CM WJWAIT_ANY The thread obtains ownership of the first 

semaphore in the list to be released. Sema¬ 
phores are checked in the order they are 
defined in the SEMRECORD array. When 
the thread has obtained ownership of one of 
the semaphores, the thread is unblocked and 
all other semaphores defined in the muxwait 
semaphore remain unchanged. 

DCMW_WAIT_ALL The thread obtains ownership of all sema¬ 

phores only when all semaphores are in the 
released state at the same time. All sema¬ 
phores become owned at the same time. 

It is an error for a thread to request a muxwait mutex semaphore if that thread cur¬ 
rently owns one or more semaphores contained in the muxwait semaphore. For both types 
of muxwait semaphores, the thread is also unblocked if a timeout period is specified and 
the semaphore request is not satisfied within that timeout period. In this case, the return 
code will be ERR0R_TIME0UT. Requests of a muxwait semaphore are made with the 
DosWaitMuxWaitSem function: 

APIRET APIENTRY DosWaitMuxWaitSem (HMUX hmux, ULONG ulTimeout, 

PULONG pulUser); 
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HMUX hmux 

ULONG ulTimeout 


PULONG pulUser 


Handle of the muxwait semaphore. 

Maximum time period to wait for the sema¬ 
phore (milliseconds). It can also be one of the 
following values: 

SEM_IMMEDIATE_RETURN Zero 

timeout 

period. 

SEM_INDEFINITE_WAIT No 

timeout 

period. 

Address of variable to receive the user field from 
the SEMRECORD of the last semaphore that 
caused the semaphore request to be satisfied. 


If the DosWaitMuxWaitSem request is successful, the ulUser field from the SEMRECORD 
of the last semaphore that caused the muxwait semaphore to be triggered or released is 
returned. The following call illustrates a request for the hmuxPrivateAll semaphore 
created earlier: 


ULONG ulUser; 
APIRET RetCode; 


RetCode = DosWaitMuxWaitSem (hmuxPrivateAll, SEM_INDEFINITE_WAIT, 
&ulUser); 

It is possible to add new semaphores to an existing muxwait semaphore. To add a 
new semaphore, the process must have both the muxwait semaphore and the new sema¬ 
phore open. A semaphore can be added even if other threads are currently waiting on the 
muxwait semaphore. The DosAddMuxWaitSem function is used to add a new semaphore. 
The semaphore must be the same type as the existing semaphores defined for the muxwait 
semaphore: 

APIRET APIENTRY DosAddMuxWaitSem (HMUX hmux, PSEMRECORD pSemRec); 

HMUX hmux Handle of the muxwait semaphore. 

PSEMRECORD pSemRec Address of new SEMRECORD structure. 

If you create a new private mutex semaphore, you can then add it to your private 
mutex semaphore as follows: 

SEMRECORD SemRecord; 

DosCreateMutexSem (NULL, &SemRecord.hsemCur, 0, FALSE); 

SemRecord.ulUser = 2; 


DosAddMuxWaitSem (hmuxPrivate, &SemRecord); 
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Notice that there is no significance to the fact you set the ulUser field to be equal to 
its index in the array. The ulUser field can contain any user-defined value. 


Any threads currently waiting on the muxwait semaphore that do not have the newly 
added semaphore opened are immediately unblocked and receive a return code of 
ERROR_INVALID_HANDLE. Other threads that subsequently call DosWaitMuxWaitSem 
must also open the new semaphore. Any thread receiving an ERROR_INVALID_HANDLE 
return code can query all the semaphores contained by the muxwait semaphore by call¬ 
ing DosQueryMuxWaitSem. Then, the thread can open those semaphores it does not cur¬ 
rently have open. It can determine which semaphores it does not have open by calling 
either DosQueryMutexSem or DosQueryEventSem and checking for a return code of 
ERROR_INVALID_HANDLE: 

APIRET APIENTRY DosQueryMuxWaitSem (HMUX hmux, PULONG pcSemRec, 
PSEMRECORD pSemRec, PULONG pflAttr); 


HMUX hmux 

PULONG pcSemRec 


PSEMRECORD pSemRec 
PULONG pflAttr 


Handle of the muxwait semaphore. 

Address of count of SEMRECORD 
structures. On input, it is the maximum 
number of structures that will fit in the 
array addressed by pSemRec. On output, it 
is the number of structures copied into the 
array addressed by pSemRec. 

Address of array to receive the 
SEMRECORD structures, 

Address of variable to receive semaphore 
attributes specified when the semaphore 
was created. The flags may contain the 
following flags: 


DC_SEM_SHARED Shared 

semaphore 
(ignored if 
pszName is 
NULL). 

D CMW_WAIT_ANY Semaphore 

request is 
satisfied when 
anyone of the 
semaphores is 
either posted 
or released. 
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DCMW_WAIT_ALL Semaphore 
request is 
satisfied only 
when all 
semaphores 
are either 
posted or 
released. 

To query our private muxwait semaphore, you can issue the following call: 

SEMRECORD SemRecords[10]; 

ULONG ulCnt; 

ULONG ulAttr; 

ulCnt = 10L; 

DosQueryMuxWaitSem (hmuxPrivate, &ulCnt, SemRecords, &ulAttr); 

The value returned in ulCnt should be three because there are three semaphores in 
the private muxwait semaphore (that is, the two original plus the one added afterward). 

It is also possible to delete semaphores from a muxwait semaphore. This is done with 
the DosDeleteMuxWaitSem function: 

APIRET APIENTRY DosDeleteMuxWaitSem (HMUX hmux, HSEM hSem); 

HMUX hmux Handle of the muxwait semaphore. 

When a semaphore is deleted from a muxwait semaphore, all threads currently wait¬ 
ing on the muxwait semaphore will be reevaluated. Deleting the semaphore may cause a 
thread to be triggered if the deleted semaphore was the only event preventing a 
DCMW_WAI T_ALL muxwait event semaphore from being triggered. It may also cause a thread 
to be unblocked if the deleted semaphore was the only semaphore preventing a 
DCMW_WAIT_ALL mutex semaphore from being released. Taking the result from the previ¬ 
ous call to DosQu e ryMuxWait Sem, you can delete the first semaphore with the following call: 

DosDeleteMuxWaitSem (hmuxPrivate, SemRecords[0].hsemCur); 

Thread Demonstration Application 

Many variables are involved in designing an effective multithreaded application. You must 
be concerned about protecting access to shared resources, setting the correct priorities of 
other threads when necessary, deciding whether a thread should contain a message queue, 
and, most important, deciding which functions should be executed in a thread. These 
design considerations and decisions can be made more competently with a good under¬ 
standing of how the various parameters involved in multithreading affect the 
performance of the individual threads and the process as a whole. The application 
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presented in this chapter is a multithreaded demonstration application that enables you 
to create both message queue and nonmessage queue threads. It is designed to enable 
you to modify dynamically various aspects of a thread so that you can view the effect of 
the changes on the thread and the other threads in the process. Specifically, you can see 
the effects of the following: 

@ Creating additional message queue threads. 

# Creating additional nonmessage queue threads. 

# Increasing and decreasing a thread’s priority. 

® Protecting a resource with a critical section. 

# Synchronizing access to a resource with a semaphore. 

# Suspending a thread. 

® Killing a thread. 

You use the CONTROLS.DLL built in Chapter 10, “Dynamic Link Libraries,” so 
we can use the THERMOMETERCLASS and BEVELCLASS controls. Every thread created is 
represented visually with a dialog window (see Figure 12.1). 


Figure 12.1. 

Dialog windows for 
message queue threads. 



TID: 1 

Priority: 512 

State: Running 


TID: 2 

Priority: 512 

• State: . Running 


TID: . 
Priority: 
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At the top of the dialog are the thread identifier, its current priority, and its current 
state. Whenever the thread is executing in its time slice and there are no messages to pro¬ 
cess, the thermometer value is either incremented or decremented. Its value will range 
from 0 to 100, and it will reverse its direction when it reaches either limit. As new threads 
are created and the CPU is distributed among more and more threads, you should see a 
decrease in the speed of each thermometer’s value. 



Real-World Programming for 


2,1 


The buttons at the bottom enable you to modify the thread’s activity and state. The 
Kill button kills the thread. The Up button increases the thread’s priority to a maximum 
of 31. The Down button decreases the thread’s priority to zero. The CritSec button al¬ 
lows use of critical sections for the thread. This means that every time the thermometer 
value is changed, the thread will enter a critical section, sleep for 1/10 second, and exit 
the critical section. The Semaphore button allows use of semaphores for the thread. This 
means that every time the thermometer value reaches zero, the thread will request the 
semaphore. When it receives the semaphore, it will continue to own the semaphore until 
it next reaches a value of zero, at which time it will release the semaphore. You can create 
as many message queue threads as your system will allow. 

The nonmessage queue thread is implemented as a sorting thread. The sorting thread 
dialog is shown in Figure 12.2. The sorting thread performs the inefficient bubblesort 
on a 4K array of unsigned long integers. It posts a percent complete message to the main 
thread that is then used to update the dialog window. At the top of the dialog is the thread 
identifier and the percent complete value. The status bar is filled to represent the percent 
complete as it changes. The buttons at the bottom enable you to modify the sorting thread’s 
activity and state. The Kill button kills the thread. The Suspend button suspends execu¬ 
tion of the thread, and the text of the button changes to Resume. The Resume button 
resumes execution of the thread. The Up and Down buttons increase or decrease the priority 
the same as before. When the sorting thread completes its sort, it terminates and the dialog 
box goes away. You can start multiple nonmessage queue sorting threads at the same time. 

Figure 12.2. 

Dialog window for a 
nonmessage queue 
thread. 


When the application is started, the main window is displayed with a message queue 
dialog window for thread 1. The Threads menu option provides options for creating new 
threads, killing all the message queue threads, and arranging the windows. The New 
Thread submenu option provides two choices: Message Queue Thread and Sorting 
Thread. These create a new thread of the appropriate type. The resources are defined by 
the following files. 

THREADS.H 

/* 

Threads Header File 
Chapter 12 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

. */ 
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/* Dialog and Control Identifiers */ 

#define ID_APPNAME 1 
#define IDD_THREADDLG 1 
#define IDD_TIDDLG 2 
#define IDD_SORTINGDLG 3 

#define IDM_THREADS 100 
#define IDM_NEWTHREAD 101 
#define IDM_NEWQMSGTHREAD 110 
#define IDM_NEWSORTINGTHREAD 111 
#define IDM_KILLALLTHREADS 102 
#define IDM_ARRANGE 103 
#define IDM_ABOUT 104 

#define IDC_THREADID 200 
#define IDC_THREADPRIORITY 201 
#define IDC_STATE 202 
#define IDC_CRITSECTION 203 
#define IDC_SEMAPHORE 204 
#define IDC_THERMOMETER 205 
#define IDC_KILL 206 
#define IDC_UPPRIORITY 207 
#define IDC_DOWNPRIORITY 208 

#define IDC_PERCENT 300 
#define IDC_PERCENTBAR 301 
#define IDC_SUSPEND 302 
#define IDC_RESUME 303 


THREADS.RC 


/* 


Threads Resource File 
Chapter 12 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


/ 


#include <os2.h> 

#include "threads.h" 

#include "..\common\controls.h 

ICON ID_APPNAME THREADS.ICO 

MENU ID_APPNAME 

{ 


SUBMENU "-Threads", 

{ 


I DM THREADS 
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} 


SUBMENU "-New Thread", IDM_NEWTHREAD 


{ 

MENUITEM "-Message Queue Thread", 
MENUITEM "-Sorting Thread", 

} 

MENUITEM "-Kill All Message Queue Threads 
MENUITEM "", -1, 

MENUITEM "A~rrange", 

MENUITEM -1, 

MENUITEM "-About...", IDM_ABOUT 


IDM_NEWQMSGTHREAD 

IDM_NEWSORTINGTHREAD 

, IDM_KILLALLTHREADS 
MIS_SEPARATOR 
IDM_ARRANGE 
MIS SEPARATOR 


STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Threads Demonstration Application 

END 


rcinclude tid.dlg 
rcinclude sort.dig 
rcinclude ..\common\about.dig 


TID.DLG 


/* 


Threads Dialog 
Chapter 12 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_TIDDLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Dialog Title", IDD_TIDDLG, 34, 40, 80, 94, 

NOT FS_DLGBORDER | NOT WS_SAVEBITS, FCF_NOBYTEALIGN 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 


CONTROL 

j 

-1,0, 0, 80, 

94, 

BEVELCLASS, 



BVS_BEVELIN 

| BVS_RECTANGLE 

| ws 

_VISIBLE 



LTEXT 

"TID:", 

-1, 4, 85, 33, 

7 





LTEXT 

"Priority:", 

-1,4, 79, 33, 

7 





LTEXT 

"State:", 

-1, 4, 73, 33, 

7 





RTEXT 

"0000", 

IDC THREADID, 


35 

85, 

21, 

7 

RTEXT 

"0000", 

IDC_THREADPRIORITY, 

35 

79, 

21, 

7 

LTEXT 

"Running", 

IDC_STATE, 


35 

73, 

44, 

7 

CONTROL 

"", IDC_THERMOMETER, 27, 22 

27, 

49, 





THERMOMETERCLASS, THS_NOPERCENT 

! ws_ 

VISIBLE 


PUSHBUTTON 

"Kill", 

IDC_KILL, 


i 

9, 

40, 

10 
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PUSHBUTTON "Up", 

IDC_UPPRIORITY, 

40, 

9, 

20, 

10 

PUSHBUTTON "Dwn", 

IDC_DOWNPRIORITY, 

© 

CD 

9, 

19, 

10 

PUSHBUTTON "CritSec", 

IDC_CRITSECTION, 

1, 

0, 

40, 

10 

PUSHBUTTON "Semaphore", 

IDC_SEMAPHORE, 

40, 

0, 

39, 

10 


END 

END 


SORT.DLG 


/* 


Sorting Thread Dialog 
Chapter 12 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_SORTINGDLG LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Sorting Thread", IDD_SORTINGDLG, 56, 92, 128, 47, 0, 
FCF_TITLEBAR | FCF_NOBYTEALIGN j FCF_NOMOVEWITHOWNER 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 


LTEXT 

"TID: ", 

-1, 

4 

CD 

CO 

33, 

7 

RTEXT 

"0000" , 

IDC_THREADID, 

35 

CD 

CO 

21, 

7 

LTEXT 

"Percent 

Complete:", -1, 

5 

, 29, 

69, 

7 

LTEXT 


-1, 

103 

. 29, 

10, 

7 

RTEXT 

"0", 

IDC_PERCENT, 

82 

, 29, 

20, 

7 

CONTROL 

"", IDC_ 

PERCENTBAR, 5, 18, 11 

8, ' 

10, WC STATIC 


SS TEXT 

| WS_VISIBLE 





PUSHBUTTON 

"Kill", 

IDC_KILL, 

4 

■ 4, 

40, 

10 

PUSHBUTTON 

"Suspend 

", IDC_SUSPEND, 

44 

. 4, 

40, 

10 

PUSHBUTTON 

"Up", 

IDC_UPPRIORITY, 

84 

, 4, 

20, 

10 

PUSHBUTTON 

" Dwn", 

IDC_DOWNPRIORITY, 

104. 

, 4, 

20, 

10 


END 

END 


THREADS.C 


/* 


Threads Program 
Chapter 12 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_DOSERRORS 
#define INCL_D0S 
#define INCL WIN 







Real-World Programming for \Js3i L 2.1 


#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include "threads.h" 

#include 11 . . \common\controls. h" 

#include "..\common\about.h" 

/* Undocumented WinDrawBorder flag */ 

#define DB_RAISED 0x0400 

/* Sorting thread structure 
#define ARRAY_SIZE 4096 
typedef struct 
{ 

HWND hWndDlg; 

ULONG ulCnt; 

ULONG ulArray[1]; 

} SORTDATA; 

typedef SORTDATA *PSORTDATA; 

/* Window and Dialog Functions */ 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY TIDDlgProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY SortingDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Thread Functions */ 

#if def_WATCOM_ 

VOID __stdcall ThermometerThread (HWND); 

VOID __stdcall SortingThread (PSORTDATA); 

#else 

VOID ThermometerThread (HWND); 

VOID SortingThread (PSORTDATA); 

#endif 

/* Local Functions */ 

VOID ArrangeThreadWindows (VOID); 

VOID CreateSortingThread (HWND); 

HWND CreateThreadWindow (HWND); 

VOID DestroyThreadWindow (HWND); 

VOID ThreadMessageLoop (HAB,HWND,HWND); 

/* User-Defined messages */ 

#define WM_USER_KILL WM_USER+1 

#define WM_USER_UPPRIORITY WMJJSER+2 

#define WM_USER_DOWNPRIORITY WM_USER+3 

#define WM_USER_CRITSECTION WM_USER+4 

#define WM_USER_SEMAPHORE WM_USER+5 

#define WM USER_PERCENTCOMPLETE WMJJSER+6 


/* Dialog window handle */ 
/* Number of entries to sort */ 
/* Array of data to sort */ 


/* Global Variables 


/ 
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HAB hab; 

HWND hWndFrame, 

hWndClient, 
hWndMainTID, 
hWndMainThermo; 

CHAR szTitle[64]; 

RECTL RectlTID; 

HMTX ThreadSem; 

ULONG ulThreadCnt = 0; 

SHORT sScrollPos = 0; 

SHORT sScrollRange = 0; 


/* Handle to anchor block */ 
/* Frame window handle */ 
/* Client window handle */ 
/* Main thread ID */ 
/* Main thermometer window */ 
/* Title string */ 
/* Thread dialog size */ 
/* Thread semaphore */ 
/* Number of QMSG threads */ 
/* Current scroll position */ 
/* Current scroll range */ 


/* . Main Application Function ..*/ 

int main() 

{ 

HMQ hmq; 

ULONG flFrameFlags = FCF_TITLEBAR j FCF_SYSMENU | FCF_IC0N | 

FCF_SIZEBORDER | FCF_MINMAX | FCF_SHELLPOSITION | 
FCF__TASKLIST ! FCF_MENU | FCF_NOBYTEALIGN | FCF_VERTSCROLL; 

CHAR szClientClass[] = "CLIENT"; 

CHAR szFailBuff [CCHMAXPATH]; 

HMODULE hDLLModule; 

hab = Winlnitialize (0L); 

hmq = WinCreateMsgQueue (hab 3 0L); 

/* Load the controls dynamic link library */ 

if (DosLoadModule (szFailBuff, sizeof(szFailBuff), "CONTROLS", 
&hDLLModule)) 

{ 

WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, 

"Unable to load CONTROLS.DLL", 

"Real World Programming in OS/2", 

0, MB_OK | MB_CRITICAL | MB_MOVEABLE); 

} 

else 

{ 

WinRegisterClass (hab, szClientClass, ClientWndProc, 
CS_CLIPCHILDREN, 0); 

WinLoadString (hab, 0L, ID_APPNAME, sizeof(szTitle), 
szTitle); 

/* Create the main application window */ 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, 0, 

&flFrameFlags, szClientClass, szTitle, 0, 0, 

ID_APPNAME, &hWndClient); 

WinShowWindow (hWndFrame, TRUE); 
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/* Create main thread thermometer window */ 
hWndMainTID = CreateThreadWindow (hWndClient); 
hWndMainThermo = WinWindowFromID (hWndMainTID, 

IDC_THERMOMETER); 

WinEnableControl (hWndMainTID, IDC_KILL, FALSE); 

WinEnableControl (hWndMainTID, IDC_SEMAPHORE, FALSE); 

/* Create the thread semaphore */ 

DosCreateMutexSem (NULL, &ThreadSem, 0L, FALSE); 

ThreadMessageLoop (hab, hWndMainTID, hWndMainThermo); 

/* Close the thread semaphore */ 

DosCloseMutexSem (ThreadSem); 

DestroyThreadWindow (hWndMainTID); 

WinDestroyWindow (hWndFrame); 

/* Release the controls dynamic link library */ 

DosFreeModule (hDLLModule); 

} 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 

return (0); 

} 

/* . Sorting Thread Function . */ 

/* 

The Sorting thread is responsible for sorting the array of unsigned 
long numbers. The input to this thread is the address of a SORTDATA 
structure. This thread is for demonstration only so it performs the 
very slow bubblesort. A WM_USER_PERCENTCOMPLETE message is posted 
to the dialog window as it completes each percent of the sorting 
process. When sorting is complete, the thread posts a 100% 
WM_USER_PERCENTCOMPLETE message to the dialog and terminates itself. 

This is a Nonmessage queue thread so it cannot send messages to 
a Message queue thread. 

*/ 

#ifdef _IBMC_ 

#pragma linkage(SortingThread, system) 

#endif 


mb 
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#ifdef_WATCOM_ 

VOID _stdcall SortingThread (PSORTDATA pData) 

#else 

VOID SortingThread (PSORTDATA pData) 

#endif 

{ 

ULONG ullnx, 
ulJnx, 

ulNewPercent, 
ulPercent , 
ulTotalComparisons, 
ulNumComparisons; 

/* Total number of comparisons = ulCnt! */ 

ulTotalComparisons = (pData->ulCnt * (pData->ulCnt +1)) / 2; 

ulNumComparisons = 0; 

ulPercent = 0L; 

/* Perform bubble sort */ 

for (ullnx = 0; ullnx < (pData->ulCnt - 1); ullnx++) 

{ 

for (ulJnx = ullnx+1; ulJnx < pData->ulCnt; ulJnx++) 
if (pData->ulArray[ulInx] > pData->ulArray[ulJnx]) 

{ 

/* Swap values using exclusive-or operation */ 
pData->ulArray[ullnx] A = pData->ulArray[ulJnx]; 
pData->ulArray[ulJnx] A = pData->ulArray[ullnx]; 
pData->ulArray[ullnx] A = pData->ulArray[ulJnx]; 

} 

/* Increment number of comparisons done so far */ 
ulNumComparisons += (pData->ulCnt - ullnx - 1); 

ulNewPercent = (ulNumComparisons * 100) / ulTotalComparisons; 
if (ulNewPercent != ulPercent) 

{ 

ulPercent = ulNewPercent; 

WinPostMsg (pData->hWndDlg, WM_USER_PERCENTCOMPLETE , 
(MPARAM)ulPercent, 0L); 

} 

} 

/* Post 100% completion message */ 

WinPostMsg (pData->hWndDlg, WM_USER_PERCENTCOMPLETE, 

(MPARAM)100L, 0L); 

DosExit (EXIT_THREADj 0L); 
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/* . Thermometer Thread Function . */ 

/* 

The Thermometer thread is responsible for simply incrementing 
and decrementing the current thermometer value. Most of the 
thread processing is performed in the ThreadMessageLoop function. 

Since this thread will be directly updating the dialog box control 
windows it must create a message queue. Thus it will be a 
Message queue thread. 

*/ 

#ifdef IBMC 

#pragma linkage(ThermometerThread, system) 

#endif 

#if def WATCOM 

VOID __stdcall ThermometerThread (HWND hWnd) 

#else 

VOID ThermometerThread (HWND hWnd) 

#endif 

{ 

HMQ hmqThread; 

HAB habThread; 

HWND hWndTIDj 

hWndThermo; 

/* Create message queue for this thread */ 
habThread = Winlnitialize (0L); 
hmqThread = WinCreateMsgQueue (hab, 0L); 

/* Create the thread window */ 

hWndTID = CreateThreadWindow (hWnd); 

hWndThermo = WinWindowFromID(hWndTID, IDC_THERMOMETER); 

ThreadMessageLoop (hab, hWndTID, hWndThermo); 

/* Destroy the thread's window */ 

DestroyThreadWindow (hWndTID); 

/* Destroy the message queue for this thread */ 

WinDestroyMsgQueue (hmqThread); 

WinTerminate (habThread); 

DosExit (EXIT_THREAD, 0L); 

} 


/ 


Local Functions 


/ 
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VOID ArrangeThreadWindows () 

{ 

HENUM hEnum; 

PSWP pSwp; 

RECTL Recti; 

ULONG ulNumPerRow, 
ulCnt = 0; 

HWND hWndThread; 

/* Allocate memory to hold the SWP structures */ 

if (!DosAllocMem ((PPVOID)&pSwp, sizeof(SWP)*ulThreadCnt, fALLOC)) 

/* Calculate number of thread windows that fit in each row */ 
WinQueryWindowRect (hWndClient, &Rectl); 
ulNumPerRow = Recti.xRight / RectlTID.xRight; 
if (ulNumPerRow == 0) 
ulNumPerRow++; 

/* Enter critical section so that the list of current windows 
remains unchanged while we enumerate */ 

DosEnterCritSec (); 

/* Begin thread window enumeration */ 
hEnum = WinBeginEnumWindows (hWndClient); 

/* Get handle to each thread window */ 

while ((hWndThread = WinGetNextWindow (hEnum)) != 0) 

pSwp[ulCnt].fl = SWP_MOVE | SWP_NOADJUST ] SWP_SHOW; 

pSwp[ulCnt].x = (ulCnt % ulNumPerRow) * 

RectlTID.xRight; 

pSwp[ulCnt].y = Recti.yTop - 

(((ulCnt / ulNumPerRow) + 1) * RectlTID.yTop); 
pSwp[ulCnt++].hwnd = hWndThread; 

} 

/* End Thread window enumeration */ 

WinEndEnumWindows (hEnum); 

/* Exit the critical section since we have enumerated all the 
current windows */ 

DosExitCritSec (); 

/* Arrange the tiled windwos */ 

WinSetMultWindowPos (hab, pSwp, ulCnt); 

/* Get the scroll range and initial position */ 
sScrollPos = 0; 

sScrollRange = (SHORT)-pSwp[ulCnt-1].y; 

WinSendDlgltemMsg (hWndFrame, FID_VERTSCROLL 3 
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SBM_SETSCROLLBAR, 

MPFROMSHORT(0), MPFR0M2SH0RT(0,sScrollRange)); 

/* Free the allocated memory */ 

DosFreeMem ((PVOID)pSwp); 


return; 

} 


VOID CreateSortingThread (HWND hWnd) 


{ 

TID 

ULONG 

PSORTDATA 

RECTL 

POINTL 


ThreadID; 

ullnx; 

pData; 

Recti; 

Ptl; 


/* Allocate a block of memory to contain the sorting data plus all 
of the array entries to sort */ 
if (IDosAllocMem ((PPVOID)&pData, 

sizeof(SORTDATA) + ((ARRAY_SIZE - 1) * sizeof(ULONG)), 
fALLOC)) 

{ 

/* Initialize array as an array of descending numbers to be 
sorted in ascending order (worst case order) */ 
for (ullnx = 0; ullnx < ARRAY_SIZE; ullnx++) 

pData->ulArray[ullnx] = ARRAY_SIZE - ullnx; 


pData->ulCnt = ARRAY_SIZE; 

/* Create dialog to display sorting status */ 
pData->hWndDlg = WinLoadDlg (HWND_DESKTOP, hWnd, 
SortingDlgProc, 0L, IDD_SORTINGDLG, NULL); 

/* Create the sorting thread in a suspended state */ 
DosCreateThread (&ThreadID, (PFNTHREAD)SortingThread, 
(ULONG)pData , 0x0001, 0x2000); 

WinSetWindowUShort (pData->hWndDlg, QWS_ID, 

(USHORT)ThreadID); 

WinSetDlgltemShort (pData->hWndDlg, IDC_THREADID, 

(USHORT)ThreadID, FALSE); 

WinSetWindowPtr (pData->hWndDlg, QWL_USER, (PVOID)pData); 

/* Position the sorting dialog */ 

WinQueryWindowRect (pData->hWndDlg, &Rectl); 

Ptl.x = Ptl.y = 0L; 

WinMapWindowPoints (hWndFrame, HWND_DESKTOP, &Ptl, 1L); 
WinSetWindowPos (pData->hWndDlg, 0L, 
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Ptl.x + (ThreadID & 1) * Recti.xRight, 

((ThreadID & 7) » 1) * Recti.yTop, 

0L, 0L , SWP_M0VE ! SWP_SH0W); 

/* Start the thread */ 

DosResumeThread (ThreadID); 

} 

return; 

} 

HWND CreateThreadWindow (HWND hWnd) 

{ 

HWND hWndTID; 

hWndTID = WinLoadDlg (hWnd, hWnd, TIDDlgProc, 0L, IDD_TIDDLG, 
NULL); 

/* Increment count of message queue threads within a critical 
section since multiple threads may be calling this function 
at the same time */ 

DosEnterCritSec(); 
ulThreadCnt++; 

DosExitCritSec(); 

WinSetWindowPos (hWndTID, HWND_B0TT0M, 0L, 0L, 0L, 0L,SWP_ZORDER); 
ArrangeThreadWindows (); 

return (hWndTID); 

} 

VOID DestroyThreadWindow (HWND hWnd) 

{ 

WinDestroyWindow (hWnd); 

/* Decrement count of message queue threads within a critical 
section since multiple threads may be calling this function 
at the same time */ 

DosEnterCritSec(); 
ulThreadCnt- -; 

DosExitCritSec(); 

return; 

} 

VOID ThreadMessageLoop (HAB hab, HWND hWndMain, HWND hWndThermo) 

{ 

APIRET RetCode; 

QMSG qmsg; 

PPIB ppib; 
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PTIB 

ptib; 


BOOL 

bContinue 

= TRUE; 

ULONG 

ulValue 

= 0L; 

LONG 

UncDec 

= 1L; 

LONG 

IPriority 

= 0L; 

ULONG 

ulCurPriority 

= 0L; 

BOOL 

bDoCriticalSection 

= FALSE 

BOOL 

bDoSemaphore 

= FALSE 

BOOL 

bHaveSemaphore 

= FALSE 


/* Message processing loop for a thread. Peek messages from the 
message queue and dispatch them as the default. If the message 
requires special processing then do it here. This function 
executes on behalf of each thread that calls it so the message 
processing is per thread using each thread's stack space. */ 

do 

{ 

while (bContinue && 

WinPeekMsg (hab, &qmsg, 0L, 0L, 0L, PM_REM0VE)) 

{ 

switch (qmsg.msg) 

{ 

case WM_QUIT: 
case WM_USER_KILL: 

bContinue = FALSE; 

/* Force release of semaphore */ 
ulValue = 0L; 

bDoSemaphore = FALSE; 
break; 

case WMJJSERJJPPRIORITY: 

/* Increase thread priority */ 
lPriority++; 

DosSetPriority (PRTYS_THREAD, PRTYC_REGULAR, 
IPriority, 0L); 

if (IPriority == PRTYDJVIAXIMUM) 

WinEnableControl (hWndMain, IDCJJPPRIORITY, 
FALSE); 

WinEnableControl (hWndMain, IDC_DOWNPRIORITY, 

TRUE); 
break; 

case WM_USER_DOWNPRIORITY: 

/* Decrease thread prioity */ 

IPriority_; 

DosSetPriority (PRTYS_THREAD, PRTYC_REGULAR, 
IPriority, 0L); 
if (IPriority == 0L) 
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WinEnableControl (hWndMain, IDC_DOWNPRIORITY, 
FALSE); 

WinEnableControl (hWndMain, IDCJJPPRIORITY, TRUE); 
break; 

case WM_USER_CRITSECTION: 

bDoCriticalSection = !bDoCriticalSection; 
break; 

case WM_USER_SEMAPHORE: 

bDoSemaphore = IbDoSemaphore; 
break; 

default: 

WinDispatchMsg (hab, &qmsg); 

} 

} 

/* No more messages in the queue */ 

/* Update thread priority in the dialog if it has changed */ 

DosGetlnfoBlocks (&ptib, &ppib); 

if (ulCurPriority != (ptib->tib_ptib2)->tib2_ulpri) 

ulCurPriority = (ptib->tib_ptib2)->tib2_ulpri; 
WinSetDlgltemShort (hWndMain, IDC_THREADPRIORITY, 
(USHORT)ulCurPriority, FALSE); 


/* If the user has indicated that this thread should enter a 
critical section, then enter a critical section and sleep 
for 100 milliseconds */ 
if (bDoCriticalSection) 

{ 

WinSetDlgltemText (hWndMain, IDC_STATE, "Crit Sec"); 
DosEnterCritSec (); 

DosSleep (100L); 

DosExitCritSec (); 

WinSetDlgltemText (hWndMain, IDC_STATE, 

bHaveSemaphore ? "Semaphore" : "Running"); 


/* Update thread thermometer value */ 

WinSendMsg (hWndThermo, THM_SETVALUE, (MPARAM)ulValue, 0L); 

I* If the thermometer value is zero, then reverse direction and 
check if the semaphore should be requested or released */ 
if (ulValue == 0) 

{ 



UncDec = 1L; 
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/* If this thread has the semaphore, then release it */ 
if (bHaveSemaphore) 

{ 

bHaveSemaphore = FALSE; 

WinSetDlgltemText (hWndMain, IDC_STATE, "Running"); 
DosReleaseMutexSem(ThreadSem); 

} 

/* If the user has indicated this thread should request 
the semaphore each time the thermometer value reaches 
zero, then request it. If after 2 seconds the thread 
hasn't received the semaphore, then continue on anyway.*/ 
if (bDoSemaphore) 

{ 

WinSetDlgltemText (hWndMain, IDC_STATE, "Req Sem"); 
RetCode = DosRequestMutexSem (ThreadSem, 2000L); 
if (RetCode == 0L) 

{ 

bHaveSemaphore = TRUE; 

WinSetDlgltemText (hWndMain, IDC_STATE, 

"Semaphore"); 

} 

else if (RetCode == ERROR_TIMEOUT) 

WinSetDlgltemText (hWndMain, IDC_STATE, 

"Sem Timeout"); 

else if (RetCode == ERR0R_SEM_OWNER_DIED) 
WinSetDlgltemText (hWndMain, IDC_STATE, 

"Sem Owner Died"); 

else 

WinSetDlgltemText (hWndMain, IDC_STATE, 

"Sem Req Error"); 

} 

/* Give lower priority threads a chance to do something */ 
DosSleep (5L); 


} 

else if (ulValue == 100) 

UncDec = -1L; 
ulValue += UncDec; 

} while (bContinue); 

return; 

} 

/* .Window and Dialog Functions . */ 

MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 
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BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

RECTL Recti; 

HPS hps; 

HENUM hEnum; 

TIC) ThreadID; 

HWND hWndThread; 

SHORT sNewScrollPos; 

switch (msg) 

{ 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0L,NULL); 
WinQueryWindowRect (hWnd, &Rectl); 

WinFillRect (hps, &Rectl, CLR_PALEGRAY); 

WinEndPaint (hps); 
break; 

case WM_SIZE: 

ArrangeThreadWindows (); 
break; 

case WM_INITMENU: 

if (SHORT1FROMMP(mp1) == IDM_THREADS) 

WinEnableMenuItem ((HWND)mp2, IDM_KILLALLTHREADS, 
(ulThreadCnt > 1L)); 

break; 

case WM_VSCROLL: 

sNewScrollPos = sScrollPos; 
switch (SH0RT2FR0MMP(mp2)) 

{ 

case SB_LINEUP: 

sNewScrollPos- -; 
break; 

case SB_LINEDOWN: 
sNewScrollPos++; 
break; 

case SB_PAGEUP: 

sNewScrollPos -= (SHORT)RectlTID.yTop; 
break; 

case SB_PAGEDOWN: 

sNewScrollPos += (SHORT)RectlTID.yTop; 
break; 

case SB_SLIDERPOSITION: 
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sNewScrollPos = SH0RT1FROMMP(mp2); 
break; 


sNewScrollPos = 

(SHORT)max (0, min (sNewScrollPos, sScrollRange)); 
if (sNewScrollPos != sScrollPos) 

{ 

WinScrollWindow (hWndClient, 0L, 

sNewScrollPos - sScrollPos, NULL, NULL, 0, NULL, 
SW_SCROLLCHILDREN | SW_INVALIDATERGN); 
sScrollPos = sNewScrollPos; 

WinSendDlgltemMsg (hWndFrame, FID_VERTSCROLL, 
SBM_SETPOS, MPFROMSHORT(sScrollPos), 0L); 
WinUpdateWindow (hWndClient); 

} 

break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_NEWQMSGTHREAD: 

DosCreateThread (&ThreadID, 

(PFNTHREAD)ThermometerThread, 

(ULONG)hWndClient, 0, 0x5000); 
break; 

case IDM_NEWSORTINGTHREAD: 

CreateSortingThread (hWnd); 
break; 

case IDM_KILLALLTHREADS: 

hEnum = WinBeginEnumWindows (hWnd); 

while (hWndThread = WinGetNextWindow (hEnum)) 

{ 

/* Don't kill the main thread */ 
if (WinQueryWindowUShort 

(hWndThread, QWS_ID) > 1L) 
WinPostMsg (hWndThread, WM_USER_KILL, 
0L, 0L); 

} 

WinEndEnumWindows (hEnum); 
break; 

case IDM_ARRANGE: 

ArrangeThreadWindows (); 
break; 

case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
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break; 

} 

default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 
return (mReturn); 


MRESULT EXPENTRY TIDDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

PPIB ppib; 

PTIB ptib; 

MRESULT mReturn = 0L; 

BOOL bHandled = TRUE; 

switch (msg) 

{ 

case WM_INITDLG: 

/* Initialize thread dialog values */ 

DosGetlnfoBlocks (&ptib, &ppib); 

WinSetWindowUShort (hWnd, QWS_ID, 

(USHORT)((ptib->tib_ptib2)->tib2_ultid)); 
WinSetDlgltemShort (hWnd, IDC_THREADID, 

(USHORT)((ptib->tib_ptib2)->tib2_ultid), FALSE); 
WinSetDlgltemShort (hWnd, IDC_THREADPRIORITY, 

(USHORT)((ptib->tib_ptib2)->tib2_ulpri), FALSE); 
WinEnableControl (hWnd, IDC_DOWNPRIORITY, FALSE); 

/* Set thermometer attributes */ 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETRANGE, 
0L, (MPARAM)100L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETVALUE, 
0L, 0L); 

WinSendDlgltemMsg (hWnd, IDC_THERMOMETER, THM_SETCOLOR, 
MPFR0M2SH0RT((ptib->tib_ptib2)->tib2_ultid % 15, 
CLR_PALEGRAY), 0L); 

/* Store the size of the thread dialog window */ 

WinQueryWindowRect (hWnd, &RectlTID); 

break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 
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{ 

case IDCJCILL: 

WinPostMsg (hWnd, WM_USER_KILL, 0L, 0L); 
break; 

case IDC_UPPRIORITY: 

WinPostMsg (hWnd, WM_USER_UPPRIORITY, 0L, 0L); 
break; 

case IDC_DOWNPRIORITY: 

WinPostMsg (hWnd, WM_USER_DOWNPRIORITY, 0L, 0L) 
break; 

case IDC_CRITSECTION: 

WinPostMsg (hWnd, WM_USER_CRITSECTION, 0L, 0L); 
break; 

case IDC_SEMAPHORE: 

WinPostMsg (hWnd, WM_USER_SEMAPHORE, 0L, 0L); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


MRESULT EXPENTRY SortingDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

TID ThreadID; 

HPS hps; 

HWND hWndCtl; 

RECTL Recti; 

MRESULT mReturn = 0L; 

BOOL bHandled = TRUE; 

switch (msg) 

{ 

case WM_USER_PERCENTCOMPLETE: 

/* Update the percent complete bar in the dialog */ 
WinSetDlgltemShort (hWnd, IDC_PERCENT, 

(USHORT)mpl, FALSE); 
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hWndCtl = WinWindowFromlD (hWnd, IDC_PERCENTBAR); 
WinQueryWindowRect (hWndCtl, &Rectl); 
hps = WinGetPS (hWndCtl); 

WinDrawBorder (hps, &Rectl, 1L, 1L, SYSCLR_BUTTONDARK, 
SYSCLRJ3UTTONMIDDLE, DB_RAISED); 

WinlnflateRect (hab, &Rectl, -1L, -1L); 

Recti.xRight = (Recti.xRight * (ULONG)mpl) / 100; 
WinFillRect (hps, &Rectl, SYSCLR_ACTIVETITLE); 
WinReleasePS (hps); 

/* If sorting is 100% complete then beep and destroy the 
status window */ 
if ((ULONG)mpl == 100L) 

{ 

DosBeep (1000L, 75L); 

DosBeep (800L, 75L); 

/* A process would now use the sorted array. Since 
this is a demonstration just free the memory */ 
DosFreeMem (WinQueryWindowPtr (hWnd, QWLJJSER)); 
WinDestroyWindow (hWnd); 

} 

break; 

case WM_COMMAND: 

ThreadID = (TID)WinQueryWindowUShort (hWnd, QWS_ID); 
switch (LOUSHORT(mpl)) 

{ 

case IDC_KILL: 

DosKillThread (ThreadID); 

DosFreeMem (WinQueryWindowPtr (hWnd, QWLJJSER)); 

WinDestroyWindow (hWnd); 

break; 

case IDC_SUSPEND: 

WinSetDlgltemText (hWnd, IDC_SUSPEND, "Resume"); 
WinSetWindowUShort ( 

WinWindowFromlD (hWnd, IDC_SUSPEND), 

QWS_ID, IDC_RESUME); 

DosSuspendThread (ThreadID); 
break; 

case IDC_RESUME: 

WinSetDlgltemText (hWnd, IDC_RESUME, "Suspend"); 
WinSetWindowUShort ( 

WinWindowFromlD (hWnd, IDC_RESUME), 

QWS_ID, IDC_SUSPEND); 

DosResumeThread (ThreadID); 
break; 

case IDG UPPRIORITY: 
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/* Increase the priority */ 

DosSetPriority (PRTYS_THREAD, PRTYC_NOCHANGE, 1L, 
ThreadlD); 
break; 

case IDC_DOWNPRIORITY: 

/* Decrease the priority */ 

DosSetPriority (PRTYS_THREAD, PRTYC_NOCHANGE, -1L, 
ThreadlD); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


We are doing something a little differently for our main message processing loop. 
Normally, an application uses aWinGetMsg loop to retrieve and process messages; how¬ 
ever, WinGetMsg does not return from the call until a message is placed in the message 
queue. Because this demonstration is showing the active CPU time of a thread, we want 
to continuously update the thermometer to show the thread’s activity. For that reason, 
we are using a WinPeekMsg loop to pull messages from the queue. As long as messages are 
in the queue, they will be retrieved and processed. When there are no more messages, the 
thread will increment or decrement its counter and update the thermometer. When a 
new message queue thread is created, it calls CreateThreadWindow. CreateThreadWindow 
loads a dialog window for the thread and increments the count of the number of message 
queue threads. Because it is possible for two threads to be in the process of creating or 
even for a thread to be terminating while another is being created, we must protect the 
ulThreadCnt variable. This is done by enclosing the incrementing of the counter in a 
critical section: 

DosEnterCritSec(); 

ulThreadCnt++; 

DosExitCritSec(); 

Likewise, the counter is protected in DestroyThreadWindow when the counter is being 
decremented: 
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DosEnterCritSec(); 
ulThreadCnt- -; 
DosExitCritSec(); 


Before examining the message processing loop and the threads, let’s look at the win¬ 
dow and dialog functions and their processing of the commands. First, we look at 
ClientWndProc. When the Message Queue Thread menu option is selected, an 
IDM_NEWMSGTHREAD command is received. This is handled by creating a new thread starting 
at the function ThermometerThread: 

case IDM_NEWQMSGTHREAD: 

DosCreateThread (&ThreadID, 

(PFNTHREAD)ThermometerThread, 

(ULONG)hWndClient, 0, 0x5000); 
break; 

Remember that when a new thread is created, its initial priority is the same as the 
thread that creates it. In this case, that is thread one. Selecting Sorting Thread will 
generate an IDM_NEWSORTINGTHREAD command, which is handled by calling 
CreateSortingThread: 

case IDM_NEWSORTINGTHREAD: 

CreateSortingThread (hWnd); 
break; 


CreateSortingThread will create a nonmessage queue sorting thread by allocating 
a block of memory to contain the 4K array of unsigned long integers. The sorting thread 
needs to receive a couple of items of information specific to the thread. This is passed to 
the thread in a SORTDATA structure: 

typedef struct 

{ 

HWND hWndDlg; 

ULONG ulCnt; 

ULONG ulArray[1]; 

} SORTDATA; 

The SORTDATA structure contains the handle of the dialog window to post its mes¬ 
sages to and the array of data to sort. With the dialog window loaded, it creates the thread 
starting at the function SortingThread: 

DosCreateThread (&ThreadID, (PFNTHREAD)SortingThread, 

(ULONG)pData, 0x0001, 0x2000); 


/* Dialog window handle */ 
/* Number of entries to sort */ 
/* Array of data to sort */ 


Note that this thread is created in a suspended state. This is needed so that the creat¬ 
ing thread can initialize the dialog fields with the thread identifier. After all post thread 
creation setup is complete, the thread is started: 
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DosResumeThread (ThreadID); 

All the message queue threads can be killed by selecting Kill All Message Queue 
Threads. The IDM_KILLALLTHREADS command is processed by enumerating all windows 
that are children of the client window. After the dialog window for a message queue thread 
is created, its identifier is set to the thread’s identifier. When the windows are enumer¬ 
ated, we can check the identifier to ensure that we do not kill thread 1. Message queue 
threads are killed by posting a message to the dialog window that will be handled by the 
thread. 

The dialog function for the message queue threads is contained in TIDDlgProc. This 
function responds to all messages generated by the buttons by posting a user message 
back to the dialog window indicating the action to perform. Because TIDDlgProc is ex¬ 
ecuting on behalf of each thread, we could handle the WM_COMMAND message in the mes¬ 
sage loop without posting another message. We will soon look at how each of these 
messages are handled in the message loop. 

The dialog function for the nonmessage queue threads is contained in 
SortingDlgProc. The dialog created for the sorting thread is owned by thread 1, and 
thus the dialog function executes as part of thread 1. As sorting is being performed, the 
thread posts a WM_USER_PERCENTCOMPLETE message with the current percentage contained 
in the mpl parameter. The dialog function updates the status bar and percent fields. If 
sorting is 100 percent complete, the application normally does something with the sorted 
data. We aren’t doing anything with it, so we free the allocated memory (pointer saved 
in the QWL_USER field of the dialog window). When a command message is received by 
the dialog function, the thread responds by killing, suspending, or resuming the sorting 
thread: 

case IDC_KILL: 

DosKillThread (ThreadID); 

DosFreeMem (WinQueryWindowPtr (hWnd, QWL_USER)); 

WinDestroyWindow (hWnd); 

break; 

case IDC_SUSPEND: 

WinSetDlgltemText (hWnd, IDC_SUSPEND, "Resume"); 

WinSetWindowUShort ( 

WinWindowFromID (hWnd, IDC_SUSPEND), 

QWS_ID, IDC_RESUME); 

DosSuspendThread (ThreadID); 

break; 

case IDC_RESUME: 

WinSetDlgltemText (hWnd, IDC_RESUME, "Suspend"); 

WinSetWindowUShort ( 

WinWindowFromID (hWnd, IDC_RESUME), 
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QWS_ID, IDC_SUSPEND); 
DosResumeThread (ThreadlD); 
break; 


When a change in priority is requested, we either increment or decrement the prior¬ 
ity without modifying the priority class: 

case IDCJJPPRIORITY: 

/* Increase the priority */ 

DosSetPriority (PRTYS_THREAD, PRTYC_NOCHANGE , 1L, 

ThreadlD); 
break; 

case IDCJDOWNPRIORITY: 

/* Decrease the priority */ 

DosSetPriority (PRTYS_THREAD, PRTYC_NOCHANGE, -1L, 

ThreadlD); 
break; 


ThreadMessageLoop handles all the message processing for all the message queue 
threads. Again, remember that this function is called on behalf of each thread. Though it 
is the same code, it is using the message queue and stack for the thread that is currently 
active. This function simply enters into a loop. At the top of the loop, the function 
retrieves any messages from the queue and either handles them locally or dispatches them. 
There is only one way out of this function, and that is to set bContinue to TPTJE. This 
is done if either the WM_QUIT or WM_USER_KILL message is received. If the 
WM_USER__UPPRIORITY or WM_USER_DOWNPRIORITY message is received, the thread ad¬ 
justs its priority: 

DosSetPriority (PRTYS_THREAD, PRTYC_REGULAR, 

IPriority, 0L); 


This time we use the other variation of DosSetPriority where we specify an ex¬ 
plicit priority class and an absolute priority level. When the WM_USER_CRITSECTION or 
the WM_USER_SEMAPHORE message is received, the corresponding flag is toggled. When 
there are no more messages to process, the function exits the WinPeekMsg loop where the 
thread priority field is updated. If this thread is performing critical section simulation, 
the thread enters into a critical section for 1/10 second: 

DosEnterCritSec (); 

DosSleep (100L); 

DosExitCritSec (); 

When the thermometer value reaches zero, we check whether the thread owns the 
semaphore. If so, the thread releases the semaphore: 
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if (bHaveSemaphore) 

{ 

bHaveSemaphore = FALSE; 

WinSetDlgltemText (hWndMain, IDC_STATE, "Running"); 

DosReleaseMutexSem(ThreadSem); 

} 

If the thread is using the semaphore simulation, the thread requests the semaphore 
with a timeout of two seconds: 

RetCode = DosRequestMutexSem (ThreadSem, 2000L); 

Each time the thermometer value reaches zero, it also calls DosSleep for 5 millisec¬ 
onds—this is to be somewhat of a good neighbor. If there are lower priority threads, they 
may be starved out by a higher priority thread. This is possible especially with this simu¬ 
lation, where the thread is constantly checking the message queue and processing with 
little chance for delay or interruption. Threads that use WinGetMsg do not have to worry 
about adding a DosSleep call, because the thread will only be doing something as long 
as messages are in the queue. 

Finally, we look at the thread functions themselves. ThermometerThread is the mes¬ 
sage queue thread. It creates a message queue, calls CallThreadWindow to get its dialog 
window, and calls ThreadMessageLoop to process all the thread messages and update 
the thermometer. When the thread receives the WM_QUIT or WM_USER_KILL message, the 
thread returns from ThreadMessageLoop, destroys the message queue, and terminates 
the thread. 

SortingThread has less to be concerned about because it does not have a message 
queue. This thread simply performs its function and terminates when done. In this case, 
it does the bubblesort while posting the WM_USER_PERCENTCOMPLETE message to the 
dialog. It also is possible for this thread to update directly the status bar in the dialog 
window by getting the handle to the presentation space and drawing directly into it. 
Because we also are updating fields in the dialog, the drawing code was kept with the 
field update code. 

Thread Observations 

Running the thread demonstration program will show you a lot about how threads work 
and how changing the various parameters affect all the other threads. Here are sugges¬ 
tions for what to try and watch for. 

ACTION Create an additional message queue thread. 

RESULT Notice that the rate at which the thermometers are 

updated slows. This is because the CPU time is 
being distributed among more threads now. 
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ACTION 

RESULT 


ACTION 

RESULT 


ACTION 

RESULT 


ACTION 

RESULT 


Create multiple message queue threads. Increase the 
priority of one thread by clicking the Up button. 
Notice that the rate at which the higher priority 
thread updates its thermometer increases, while all 
other threads slow down considerably. This is 
because as long as the higher priority thread is ready 
to run, it will receive the next time slice before any 
lower priority threads. The other threads will slowly 
change because the higher priority thread is period¬ 
ically calling DosSleep. 

Create multiple message queue threads. Click the 
CritSec button for one of the threads. 

Notice that all the thermometers’ changes seem 
jumpy. This occurs because each time the thread 
that is clicked changes its thermometer value, it 
enters a critical section. Entering a critical section 
causes all other threads to be suspended until the 
critical section is exited. 

Create multiple message queue threads. Click the 
Semaphore button for two or more threads. 

Only one of the threads with semaphores enabled 
should be updating its thermometer at any time. 
This occurs because each time one thread’s ther¬ 
mometer value reaches zero, it requests the sema¬ 
phore. Because only one thread can own the 
semaphore at a time, the other threads will be 
blocked until the semaphore is released. The only 
exception to this is when the semaphore requests 
timeout, in which case the timed-out thread will 
become unblocked and continue. You will see this 
occur when you have several message queue threads 
with semaphores enabled in each. 

Create multiple message queue threads. Move the 
mouse over each thread window. 

The thermometer for the thread under the mouse 
will be updated at a higher rate while the mouse is 
being moved. Moving the mouse over a window 
causes a WM_HITTEST message to be sent to the 
window under the mouse. Sending this message 
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causes the priority of the window receiving the 
message to be increased temporarily so that it 
can respond quickly to the message. 

ACTION 

RESULT 

Create a sorting thread window. 

Again, notice that the thermometers for the message 
queue windows will be updated at a slower rate. 

ACTION 

RESULT 

Create multiple sorting thread windows. Move the 
mouse over the sorting thread windows. 

Notice that the sorting threads do not execute at a 
faster rate, in general. This is because the dialog 
windows are created by thread 1 , and it is thread 1 
that is receiving the WM_HITTEST messages, not 
the sorting threads. There is, therefore, no need to 
increase the priority of the sorting thread in order to 
respond to the message sent. 

ACTION 

RESULT 

Create multiple message queue threads. Create a 
sorting thread window. Suspend the sorting thread. 
Move the mouse over the sorting thread window. 
The thermometer for thread 1 will change at a faster 
rate than the other message queue thermometers. 
This is because the sorting dialog window is created 
by thread 1, and it is thread 1 that is receiving the 
WMJHITTEST messages, thus getting a temporary 
boost in priority. 

It is worth noting that in most multithreaded applications, only one message queue 
thread is dedicated to processing messages, while all other threads are for performing 
specific functions such as drawing, calculating, or printing. As mentioned earlier, this 
application is used to demonstrate visually the effect of various changes to threads. 
Experiment with creating different threads and trying different options. You may be 
surprised how well OS/2 handles the various situations, and more importantly, you may 
see how to optimize your threads. 

In addition to this application, several other applications in this book use 
multithreading. The one in Chapter 11, “Printing,” shows how an application prints. 
With a few minor alterations, the application is changed to perform the printing in 
a thread. In the file PRNT.C, the WM_START_PRINT message is modified to call 
DosCreateThread: 
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case WM_START_PRINT: 

if (SH0RT1FROMMP(mp2) == IDM_PRINT) 
process_print((HWND)mpl); 

else 

DosCreateThread(&tid,(PFNTHREAD)process_print,(ULONG)mpl, 
0,0x2000); 

break; 

Because the process_print function makes a copy of the DEVICEINFO data, each 
print thread will have its own copy and can print independently of other activity in the 
application. Note, however, that the print application is merely printing predefined graph¬ 
ics commands. If your application, for example, is printing the contents of a file currently 
being edited, additional work must be done either to make a copy of the file to be printed 
or to synchronize updates to the file with what is currently being printed by the print 
thread. 

Chapter 14 presents a communications program that shows how to use a separate 
thread to monitor the status of the communications port and another thread to process 
input from the communications port. 

Chapter 15 also uses multithreading to perform a file search on any drive while 
enabling the user to continue interacting with the application. 
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Introduction 

OS/2 2.1 gives you the power of 32-bit programming and memory addressing. Although 
all new programming for OS/2 should be done using the 32-bit APIs and 32-bit compil¬ 
ers, there might be compatibility issues and justifications for continuing to use some 
existing 16-bit modules. Perhaps you are using a third-party DLL that is 16-bit 
code, but the vendor is not supplying a 32-bit version. Or what about 
that 16-bit DLL everyone is using, but nobody seems to be able 
_ , to the source for, so that it can be recompiled as 32-bit 

code? Although the 32-bit purist will undoubtedly cringe at the 
* Sff * thought of continuing to use 16-bit code, it might be a necessity 
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This chapter discusses how you can code your 32-bit application and still call into 
that old 16-bit code. It is also possible to call from 16-bit code back into 32-bit code 
by reversing the procedures discussed here. Also, be aware that although OS/2 2.1 
still supports 16-bit code, future versions of OS/2 may not support it, so it is in 
your best interest to migrate that 16-bit code as soon as possible. In the interim, there 
is a solution. 

Many of the 32-bit compilers for OS/2 support the capability to call 16-bit func¬ 
tions from 32-bit code by using high-level C language keywords (_f arl 6 and _seg16). 
Use of these keywords to define and call 16-bit functions from 32-bit code is the quick¬ 
est and safest route to accomplishing this task. Although these keywords will be used in 
the sample application (specified by conditional code for specific compilers), the discus¬ 
sion in the chapter will focus on the low-level details of calling 16-bit code from 32-bit 
code. This should be a concern to you only if you are using a compiler that does not 
support the _far16 and _seg16 keywords. Even if your compiler does support these 
keywords, it may be helpful to understand the issues involved in this process. These is¬ 
sues are discussed next. 

Tiled Memory 

In Chapter 9, “Memory Management,” we discussed how the segmented world of 16-bit 
addresses can co-exist with the 32-bit addressing in the flat memory world. Remember 
that when memory is allocated using the 16-bit segmented allocation scheme, a selector 
is allocated from the LDT (Local Descriptor Table). This selector is combined with a 
16-bit offset to form a 16:16 address, with the first byte of the allocated memory starting 
at offset zero. When memory is allocated using the 32-bit flat memory scheme, a portion 
of addressable memory is allocated, and a 32-bit offset is returned. This 32-bit offset, or 
address, is the virtual memory address of the allocated object. 

To support both addressing schemes, OS/2 implements a concept called tiled memory, 
which aligns all 16-bit segment allocations to multiples of 64K. Every 16-bit selector maps 
to a unique address in the 32-bit flat memory address space, as is shown in Figure 13.1. 

This diagram shows how the 16-bit selectors map to their 32-bit flat memory ad¬ 
dress. Because there are at most 8192 LDT selectors, the maximum address for tiled 
memory is 512M. Memory allocated in this tiled area can be addressed by both 32-bit 
and 16-bit applications. All that is required for these two types of applications to com¬ 
municate with each other is a way to convert the addresses so that the address is in an 
understandable format. 



Chapter 13 Calling 16-Bit Code 


Figure 13.1. 

16-bit selectors map to 
their tiled memory 
address. 
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Data Address Conversion 

Obviously, 32-bit code will use the 32-bit flat address, and 16-bit code will use the 16:16 
segmented address. Prior to passing an address from 32-bit code to 16-bit code, the ad¬ 
dress must be converted to the proper segmented address. For addresses that refer to data 
segments, this conversion is relatively simple. 


Tip; The compiler will automatically perform the necessary conversion of data 
addresses when the _f arl 6 or _seg16 keyword is used (check your compiler 
documentation). 


Because all 16-bit data selectors map to the start of a 64K block of memory, the off¬ 
set portion remains unchanged. We need only convert to the proper selector. This can be 
accomplished with the following macro: 

#define C0NVERT_T0_16_BIT_ADDRESS(pMem) \ 

(MAKEP((HIUSH0RT(pMem) « 3 j 7), L0USH0RT(pMem))) 

Remember that because the first 64K of memory is reserved by the system, it is in¬ 
valid to have a selector value of 7. For this reason, you should check for addresses below 
0x10000: 

if ((ULONG)pMem >= 0x10000) 

pMem = C0NVERT_T0_16_BIT_ADDRESS(pMem); 

else 

/* Error -- Invalid address */ 


am 
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If you are working in assembler, the sequence of instructions to convert the address 
is as follows: 


MOV 

EAX,pMem 

OR 

EAX,EAX 

JZ 

ZEROERR 

ROR 

EAX,16 

SHL 

AX, 3 

OR 

AL, 7 

ROL 

EAX,16 


ZEROERR: 

The conversion from the 16-bit segmented address back to the 32-bit flat address is 
easier. The following macro can be used to perform the conversion: 

#define C0NVERT_T0_32_BIT_ADDRESS(pMem) \ 

(MAKEP((HIUSHORT(pMem) » 3), LOUSHORT(pMem))) 

The assembler instructions to perform this conversion are as follows: 

MOV EAX,pMem 
ROR EAX,16 
SHR AX,3 
ROL EAX,16 

With these conversion macros at our disposal, we can now convert data addresses 
with little problem. However, we must be aware of one situation when addressing data 
objects by both 32-bit and 16-bit code. Consider the case of a 32-bit application allocat¬ 
ing a buffer in memory and wanting to pass the address of an object that crosses a 64K 
boundary, as shown in Figure 13.2. 


Figure 13.2. 
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In this example, the data starts at address 0x00C6F700 and ends at address 
0x00C71050. If we were to convert this address to a 16-bit segmented address, the start¬ 
ing address would be 63F:F700. Because a selector can only address 64K of data, the 
selector 63F could only address to 63F:FFFF, being unable to address the rest of the data 
item. For this reason, care must be taken when passing data from 32-bit code to 16-bit 
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code. If a data object crosses over a 64K boundary, you will have to make a copy of the 
data to an address that allows the data object to fit within a 64K area and then pass this 
new address to the 16-bit code. Another option is to declare initially the data in a tiled 
memory object so that the data fully resides within a 64K boundary. If the 16-bit code 
recognizes huge data segments and can properly increment its selector, this concern should 
not be a problem. 

Conversion of data addresses should be done in the 32-bit code for two reasons. If 
you had access to the 16-bit code, it would be easier to convert it to 32-bit code than to 
attempt to insert address conversion. Also, if the other code must remain 16-bit code, it 
must support a 16-bit interface, and thus the 32-bit code would be responsible for all 
conversion of addresses. 

Code Address Conversion 

One might imagine that converting addresses of code segments between the two addressing 
schemes would be the same as for data segments. Of course, one would only be imagin¬ 
ing! The truth of the matter is that converting the address of code segments is a little 
more difficult. Converting addresses of code segments is necessary when passing the ad¬ 
dress of functions or the address of data stored in a code segment. The difficulty arises 
out of OS/2’s use of segment packing to more effectively load code segments in memory. 

Segment packing in OS/2 is controlled by the MEMMAN statement in the CONFIG.SYS 
file. By default, segment packing is enabled: 

MEMMAN=SWAP,PROTECT 

Segment packing can be disabled by adding the NOPACK option: 

MEMMAN=SWAP,PROTECT,NOPACK 

Normally, when an application with multiple code segments is loaded in memory, 
each code segment is aligned to start on a 64K boundary to support the tiled addressing, 
as shown in Figure 13.3. 

Unless each code segment is nearly 64K in size, a lot of address space can be taken up 
by the code, especially if the application has many code segments. To more effectively 
utilize this space, OS/2 implements segment packing. When segment packing is enabled, 
OS/2 will pack each code segment immediately after the previous segment, as shown in 
Figure 13.4. 

Notice that the selector for the second code segment is no longer aligned on a mul¬ 
tiple of 64K. This breaks the rule that we stated earlier whereby all selectors mapped nicely 
to addresses in multiples of 64K. Also notice that flat memory address 0x00030000 is no 
longer addressable by the 16-bit code. This presents a problem in converting code seg¬ 
ment addresses because we must be able to handle the cases with and without segment 
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packing. Fortunately, there are two undocumented APIs provided in OS/2 to automati¬ 
cally convert the addresses. These APIs work both for code and data segment addresses. 


Figure 13.3. 

Code segments without 
segment packing. 
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Figure 13.4. 

Code segments with 
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segment packing. 
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(end segment) 
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The APIs Dos32FlatToSel and Dosl 6FlatToSel are used to convert from a 32-bit 
flat address to a 16-bit segmented address: 

ULONG Dos32FlatToSel(ULONG pMem); 

ULONG Dosl6FlatToSel(ULONG pMem); 

The APIs Dos32SelToFlat and Dosl 6SelToFlat are used to convert from a 16-bit 
segmented address to a 32-bit flat address: 

ULONG Dos32SelToFlat(ULONG pMem); 

ULONG Dosl6SelToFlat(ULONG pMem); 

All four of these functions must be defined so that the parameter pMem is passed in 
the eax register. For example, in the IBM C/Set compiler, this can be done with the 
_Optlink statement. Otherwise, you can call these functions from an assembler module 
or from inline assembler code. The following examples use inline assembler. 
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Tip; The compiler will automatically perform the necessary conversion of data 
addresses when the __f arl 6 keyword is used (check your compiler documentation). 


To convert from 32-bit function address to 16-bit selector address: 

PFN pfnFunction; 

_ASM { MOV EAX,pfnFunction } 

_ASM { call Dos32FlatToSel } 

_ASM { MOV pfnFunction,EAX } 

To convert from 16-bit selector function address to 32-bit flat address: 

PFN pfnFunction; 

_ASM { MOV EAX,pfnFunction } 

_ASM { call Dos32SelToFlat } 

_ASM { MOV pfnFunction,EAX } 

Conversion of code segment addresses is not done often as function addresses are 
usually resolved at link time. It is really only necessary when dynamically passing a func¬ 
tion for callback purposes. For example, you may call a function to enumerate all ele¬ 
ments of a list and call back into a function with the address of each element. 


Structure Alignment 

When sharing data structures between 16-bit and 32-bit code, consideration must be given 
to the alignment of the data elements in the structure. When offsets to elements of a data 
structure are assigned by the compiler, the compiler will use the current packing option 
to align the elements based on their size and location in the structure. The default align¬ 
ment for 16-bit code is word alignment, whereas for 32-bit code it is double word align¬ 
ment. The current alignment applied to a data structure can be controlled by either a 
compiler command-line option or by inserting a compiler pragma statement. 

Let’s look at a structure and see where the individual elements are positioned in 
memory: 


offsets 

word alignment double word alignment 


typedef struct 
{ 

CHAR cFldl; 

0 

0 

ULONG 

ulFld2; 

2 

4 

CHAR 

cFld3; 

6 

8 

ULONG 

ulFld4; 

8 

12 

USHORT 

usFld5; 

12 

16 
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USHORT usFld6; 14 18 

} SAMPLE; 

The total size of the structure for word alignment is 16 bytes, whereas for double 
word alignment it is 20 bytes. Also note that using double word alignment does not force 
all elements to begin on a double word boundary. Double word alignment forces all el¬ 
ements of double word size to be aligned on double word boundaries. Word alignment 
forces all elements of word size or greater to be aligned on word boundaries. Byte size 
elements are always positioned at the current byte. 

As you can see, if the same structure is defined in both 16-bit and 32-bit code while 
using the default packing options, there will be problems when the data structure is passed 
between the two modules. The safest thing to do when sharing data structures between 
the two memory models is to use the packing option for the 16-bit code when defining 
the structure in the 32-bit code. If the default packing was used in the 16-bit code, use 
word packing. Using the pragma statement in the code, it would look like this: 

#pragma pack(2) /* Set word alignment packing */ 

typedef struct 

{ 

CHAR cFldl; 

ULONG ulFld2; 

CHAR cFld3; 

ULONG ulFld4; 

USHORT usFld5; 

USHORT usFld6; 

} SAMPLE; 

#pragma pack() /* Reset alignment to previous packing */ 

Note that the format of the packing pragma may be different for the compiler you 
are using. 

Thunks 

The only thing remaining for us to do is call the existing 16-bit code. This process is 
called thunking and refers to the transition from executing 32-bit code to executing 16- 
bit code. The piece of code that makes the transition is called a thunk. Why is a thunk 
necessary? There are two reasons. The first is how parameters are pushed on the stack. 
The 32-bit stack is double word aligned, whereas the 16-bit stack is word aligned. When 
32-bit code pushes actual parameters onto the stack, it usually pushes double word val¬ 
ues. The 16-bit code may be expecting to receive parameters pushed as word values. The 
second reason is that the stack is addressed differently in the two models. The 32-bit code 
is addressing the stack as a 32-bit address while the 16-bit code is addressing the stack as 
a 16:16 segmented address. Thus, the registers must be set up properly for each side of 
the call. 
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For the purposes of this book, we are only interested in supporting calls into old ex¬ 
isting 16-bit code, so we will only look at calling from 32-bit code into 16-bit code. The 
sequence of steps in constructing a thunk is as follows: 

1. Push parameters, again using word alignment. 

2. Preserve the necessary registers (EBP, EBX, EDI, ESI, ES). 

3. Change the stack to 16:16 format. 

4. Call the 16:16 function. 

5. Restore preserved registers. 

Unfortunately, writing a thunk requires writing a little assembly code. There are sev¬ 
eral ways to write thunks. The approach we will take is to write a generic thunk that 
performs steps 2 through 5. The calling code will be responsible for pushing the pa¬ 
rameters onto the stack (step 1) and additionally pushing the 16-bit function address. A 
function-specific thunk will be written for each 16-bit function to be called. The func¬ 
tion-specific thunk will convert parameters that are addresses or addresses contained within 
structures pointed by a parameter to their 16-bit equivalent, push the parameters onto 
the stack using word alignment, push the function address of the 16-bit function, and 
then call the generic thunk. If the return value is an address or if addresses are contained 
in structures pointed to by parameters, the thunk will convert these addresses back to 
their 32-bit equivalent. Once we have one thunk written, creating an additional thunk 
involves nothing more than creating this small thunk code. Figure 13.5 shows the flow. 


Figure 13.5. 

The flow of creating 
a thunk. 


32-bit code 


push parameters 
call Thunkl-— 


Thunkl :<*- 


convert addresses and 
push size of parameters 
push 16-bit function address 

call generic thunk-— 

return 


Generic Thunk:-^- 

preserve registers 
switch stack 

jump to 16-bit code segment- 
restore registers 


16-bit code 
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It is important for the 32-bit thunk code to reside in a 32-bit code segment and for 
the 16-bit thunk code to reside in a 16-bit code segment. We will examine how to do 
this and the code to perform the thunks when we discuss the sample thunk application 
in the next section. 
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Thunk Application 

The Thunk application is a simple little 32-bit application that presents a dialog box 
displaying information about this book. The book information is contained within a 16- 
bit DLL, and the 32-bit application must call into the 16-bit DLL to retrieve the book 
information. Although this is not a complicated example, it demonstrates how to call 
into the 16-bit code from 32-bit code. It also shows how to pass addresses and convert 
them back and forth. Figure 13.6 shows the main window. Selecting the Booklnfo menu 
option will call the thunked function and display the Booklnfo dialog (Figure 13.7). 


Figure 13.6. 

The Thunks application. 



Figure 13.7. 
The Booklnfo 
dialog box. 



The code in this application demonstrates both methods for calling into the 16-bit 
code. Conditionally, compiled code has been inserted for those compilers that support 
the _f arl 6 and _seg16 keywords. You may notice immediately that the amount of 32- 
bit code required to call the 16-bit code is greatly reduced when this method is used. The 
other case where the compiler does not support these keywords requires the use of our 
thunks. 

We first take a quick look at the 16-bit code. Remember that we should only be us¬ 
ing existing 16-bit code if there is no way to convert it to 32-bit code. If at all possible, it 
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would certainly be best to convert code you must use in order to avoid these complica¬ 
tions. In the meantime, let’s assume we have a 16-bit DLL called BOOK16. Note that 
the BOOK16 DLL is built using a 16-bit compiler. 


BOOK16.DEF 

LIBRARY B00K16 

DESCRIPTION 'Book16 16-bit Code 1993 Blain, Delimon, & English 1 

DATA SINGLE 

EXPORTS 

GetBooklnformation @1 
GetAuthorBylndex @2 


This DLL has two functions called GetBooklnf ormation and GetAuthorBylndex. 


BOOK16.C 


/* 


Book16 16-Bit Dynamic Link Library 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "book16.h" 

CHAR szBookTitle[] = "Real World Programming for OS/2"; 

CHAR szAuthors[3][13] = 

{ 

"Derrel Blain", 

"Kurt Delimon", 

"Jeff English" 

}; 


VOID EXPENTRY GetBooklnformation (PBOOKINFORMATION pBooklnfo) 

{ 

pBooklnfo->usNumAuthors = 3; 
pBooklnfo->pszBookTitle = szBookTitle; 
return; 

} 

PSZ EXPENTRY GetAuthorBylndex (USHORT uslnx) 

{ 

return ((PSZ)((uslnx < 3) ? &szAuthors[uslnx] : NULL)); 
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The function GetBooklnf ormation takes as input a pointer to a BOOKINFORMATION 
structure. This structure contains a field for the number of authors and a pointer to the 
title of the book, both of which are filled in by this function. 


BOOK 16 .H 


/* 


Bookl6 Header File 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


typedef struct 

{ 

USHORT usNumAuthors; 

PSZ pszBookTitle; 

} BOOKINFORMATION; 

typedef BOOKINFORMATION FAR *PBOOKINFORMATION; 

VOID EXPENTRY GetBooklnformation (PBOOKINFORMATION); 

PSZ EXPENTRY GetAuthorBylndex (USHORT); 

The function GetAuthorBylndex takes as input an index to the name of the author 
to return and returns a pointer to the author name matching that index. 

There are three areas of concern in calling these functions from 32-bit code: 

1. In the GetBooklnformation function, we need to pass the address of the 
structure as its parameter. This address will have to be converted from its 32-bit 
flat address to its equivalent 16-bit segmented address. 

2. The structure BOOKINFORMATION contains a pointer as one of its fields. Upon 
return from calling the 16-bit function, we will need to convert this address 
from its 16-bit segmented address to its equivalent 32-bit flat address. Also note 
that because a structure is shared between the two sets of code, we need to be 
concerned with structure alignment. 

3. Finally, the GetAuthorBylndex function returns the address of the author 
name. This address will likewise have to be converted from its 16-bit segmented 
address to its equivalent 32-bit flat address. 

The main application consists of nothing more than the code to display the main 
application window and the book information dialog box. 
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THUNKS.DEF 

NAME THUNKS WINDOWAPI 

DESCRIPTION 'Thunks Program 1993 Blain, Delimon, & English' 
PROTMODE 


HEAPSIZE 4096 

STACKSIZE 16384 


EXPORTS 

ClientWndProc 

@1 

BooklnfoDlgProc 

@2 

AboutDlgProc 

@3 


THUNKS.RC 

/* . 

Thunks Resource File 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 

#include <os2.h> 

#include "thunks.h" 

ICON ID_APPNAME THUNKS.ICO 

MENU ID_APPNAME 

{ 

MENUITEM "-Booklnfo", IDM_B00KINF0 

MENUITEM "-About...", IDM_AB0UT 

> 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "32->16 Thunking Application" 

END 

rcinclude bookinfo.dlg 
rcinclude ..\common\about.dig 


BOOKINFO.DLG 


/* 


Book Information Dialog 
Chapter 13 
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Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


DLGTEMPLATE IDD_BOOKINFO LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Book Information", IDD_B00KINF0, 83, 85, 195, 51, 
WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR 

BEGIN 

LTEXT "Title:", -1, 3, 39, 25, 8 

ENTRYFIELD IDC_TITLE, 44, 39, 146, 8, 

ES_MARGIN | ES_READONLY 
LTEXT "Authors:", -1, 3, 28, 38, 8 

LISTBOX IDC_AUTHORLIST, 44, 3, 146, 32 


END 


END 


THUNKS.H 


/* 


Thunks Header File 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


/* Word align any structures shared with the 16-bit code */ 
#pragma pack(2) 

#if defined (_BORLAND_) 

typedef struct 

{ 

USHORT usNumAuthors; 

char __far16 *pszBookTitle; 

} BOOKINFORMATION; 

typedef BOOKINFORMATION __far16 *PBOOKINFORMATION; 

extern VOID __far16 pascal GetBooklnformation (PBOOKINFORMATION); 
extern char far16 * far16 pascal GetAuthorBylndex (USHORT), 

#elif_IBMC_ 

typedef struct 

{ 

USHORT usNumAuthors; 

char * _Seg16 pszBookTitle; 

} BOOKINFORMATION; 

typedef BOOKINFORMATION * _Seg16 PBOOKINFORMATION; 
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extern VOID _Far16 _Pascal GetBooklnformation (PBOOKINFORMATION); 
extern char * _Seg16 ( _Far16 _Pascal GetAuthorBylndex (USHORT)); 

#else 

#include "book16.h" 

extern VOID APIENTRY _THUNK_GetBookInformation (PBOOKINFORMATION); 
extern PSZ APIENTRY _THUNK_GetAuthorByIndex (USHORT); 

#endif 

#pragma pack() 


/* Dialog and Control Identifiers */ 


#define 

ID_APPNAME 

1 

#define 

IDD_BOOKINFO 

2 

#define 

IDM_BOOKINFO 

100 

#define 

IDM_AB0UT 

101 

#define 

IDC_TITLE 

200 

#define 

IDC_AUTHORLIST 

201 


THUNKS.C 

/* . 

Thunks Program 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


#define INCL_WIN 
#define INCL_GPI 

#include <os2.h> 

#include "thunks.h" 

#include "..\common\about.h" 

/* Window and Dialog Functions */ 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 
MRESULT EXPENTRY BooklnfoDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Global Variables */ 


HAB 

hab; 

HWND 

hWndFrame, 


hWndClient; 

CHAR 

szTitle[64] 
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int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR j FCF_SYSMENU j FCF_ICON 

FCF_SIZEBORDER j FCF_MINMAX | FCF_MENU 
FCF_SHELLPOSITION J FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

/* Create the main application window */ 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 

} 

/* . Window Function . 

MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_ERASEBACKGROUND: 
mReturn = MRFROMLONG(1L); 
break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDM_BOOKINFO: 

WinDlgBox (HWND_DESKTOP, hWnd, BooklnfoDlgProc, 

0L, IDD_BOOKINFO, NULL); 


break; 
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case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 

} 

if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 
return (mReturn); 

} 

MRESULT EXPENTRY BooklnfoDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0; 

BOOL bHandled = TRUE; 

BOOKINFORMATION Booklnfo; 

USHORT uslnx; 

PSZ pszAuthor; 

switch (msg) 

{ 

case WM_INITDLG: 

/* Call the thunk routine to call into the 16-bit function */ 

#if defined ( BORLAND ) |] ( IBMC ) 

GetBooklnformation (&BookInfo); 

#else 

_THUNK_GetBookInformation (&BookInfo); 

#endif 

WinSetDlgltemText (hWnd, IDC_TITLE, Booklnfo.pszBookTitle); 

for (uslnx = 0; uslnx < Booklnfo.usNumAuthors; uslnx++) 

{ 

/* Call the thunk routine to call into the 16-bit function */ 

#if defined ( BORLAND ) ]j ( IBMC ) 

pszAuthor = GetAuthorBylndex (uslnx); 

#else 

pszAuthor = _THUNK_GetAuthorByIndex (uslnx); 

#endif 


WinSendDlgltemMsg (hWnd, IDC_AUTHORLIST, 

LM_INSERTITEM, (MPARAM)LIT_END, (MPARAM)pszAuthor); 
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break; 
default: 

bHandled = FALSE; 
break; 


if (IbHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


One of the things we had to be concerned about was structure alignment of the 
BOOKINFORMATION structure. Because the 16-bit code was compiled with word alignment 
we must make sure that the definition of this structure in the 32-bit is also word aligned. 
In the THUNKS.H header file we have enclosed the BOOK16.H header file with the 
#pragma pack(2) statement to activate word alignment for all structures contained within 
that file: 

#pragma pack(2) 

#include "book16.h" 

#pragma pack() 

Also in the THUNKS.H file are two prototypes for the thunk functions that will be 
used to call into the 16-bit code: 

extern VOID APIENTRY _THUNK_GetBookInformation (PBOOKINFORMATION); 
extern PSZ APIENTRY _THUNK_GetAuthorByIndex (USHORT); 

Notice that if_ BORLAND _is defined, the_ f arl 6 keyword is used, and if_ IBMC_ _ 

is defined, both the _Far16 and _Seg16 keywords are used. The code for calling the 16- 
bit functions in both these cases will be generated automatically by the compiler. In these 
cases, the 16-bit functions will be called by their actual names (GetBooklnf ormation 
and GetAuthorBylndex). 

We will examine these functions shortly. By selecting the Booklnfo menu option, 
you will see a book information dialog box. During the WM_INITDLG message processing 
for this dialog, we call the two thunk functions: 

BOOKINFORMATION Booklnfo; 

USHORT uslnx; 

PSZ pszAuthor; 

case WM_INITDLG: 

/* Call the thunk routine to call into the 16-bit function */ 
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#if defined(__BORLAND__) | | (__IBMC__) 

GetBooklnformation (&BookInfo); 

#else 

_THUNK_GetBookInformation (&BookInfo); 

#endif 

WinSetDlgltemText (hWnd 3 IDCJITLE, Booklnfo.pszBookTitle); 

for (uslnx = 0; uslnx < Booklnfo.usNumAuthors; uslnx++) 

{ 

/* Call the thunk routine to call into the 16-bit function */ 
#if defined(__B0RLAND__) |] (__IBMC__) 

pszAuthor = GetAuthorBylndex (uslnx); 

#else 

pszAuthor = _THUNK_GetAuthorByIndex (uslnx); 

#endif 

WinSendDlgltemMsg (hWnd, IDC_AUTHORLIST, 

LM_INSERTITEM, (MPARAM)LIT_END, (MPARAM)pszAuthor); 

} 

break; 


Both calls to the thunk functions are formatted just as if we were calling the 16-bit 
function directly, except we are calling the thunk function. All the conversion work is 
done in the thunk code contained in THUNKASM.ASM file. 

THUNKASM.ASM 


Thunks Assembler File 
Chapter 13 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


; THUNKASM.ASM 

; Generic thunk code for calling from 32-bit code to 16-bit code 

; Each 16-bit function to be called is defined here with the _THUNK_ 

; prefix 

; Expected calling convention for _THUNK_... functions is _syscall 

; Each __THUNK_... function re-pushes the parameters onto the stack 
; using word alignment. Parameters which are addresses or fields 
; within structures which are addresses are converted and pushed onto 
; the stack. All parameters are pushed onto the stack using the 
; pascal calling convention (left to right). 
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D0_THUNK is the generic thunk function 


TITLE THUNKASM 
. 386P 

_TEXT32 SEGMENT DWORD USE32 PUBLIC 'CODE 1 

EXTRN Dos32FlatToSel:NEAR 
EXTRN Dos32SelToFlat:NEAR 
_TEXT32 ENDS 

_TEXT16 SEGMENT WORD USE16 PUBLIC ‘CODE 1 
EXTRN GetBooklnformation:FAR 

EXTRN GetAuthorBylndex:FAR 
_TEXT16 ENDS 

PUBLIC _THUNK_GetBookInformation 
PUBLIC _THUNK_GetAuthorByIndex 


32-BIT CODE SEGMENT 


TEXT32 SEGMENT 

ASSUME CS: FLAT, DS: FLAT, ES: FLAT 
THUNK_GetBookInformation PROC NEAR 

; --- save the registers --- 
push ebp ; push stack frame 

mov ebp, esp ; set new stack frame 


; -- push function parameters 


mov 

eax, 

DWORD PTR [ebp+8] ; move 1st parameter 

to eax 

call 

Dos32FlatToSel ; convert from 32-bit 

to 16:16 

push 

eax 

; push 1st parameter 

(16:16) 



; --- push 16-bit function 

mov 

eax, 

SEG GetBooklnformation 


shl 

eax, 

16 


or 

eax, 

OFFSET GetBooklnformation 


push 

eax 




mov ecx, 4 ; 

call _DO_THUNK 

mov ecx, DWORD PTR [ebp+8] 

mov eax, DWORD PTR [ecx+2] 


set size of parameters 

; thunk to the 16-bit function 

; address of structure to ecx 
; address of field to eax 
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call Dos32SelToFlat ; convert structure address 

mov DWORD PTR [ecx+2], eax ; move info structure to field 

leave 

ret 

THUNK_GetBookInformation ENDP 


THUNK_GetAuthorByIndex PROC NEAR 


; — save the registers — 
push ebp ; push stack frame 

mov ebp, esp ; set new stack frame 




; --- push 

function parameters 

push 

WORD 

PTR [ebp+8] ; push 1st 

parameter (uslndex) 



; --- push 

16-bit function 

mov 

eax, 

SEG GetAuthorBylndex 


shl 

eax, 

16 


or 

eax, 

OFFSET GetAuthorBylndex 


push 

eax 



ecx 

i 2 

; set size of 

parameters 


call __DO_THUNK 

call Dos32SelToFlat 

leave 

ret 

THUNK_GetAuthorByIndex ENDP 

DO_THUNK PROC NEAR 

push ebp 

mov ebp, esp 

push ebx 

push edi 

push esi 

push es 

mov eax, esp 

push ss 

push eax 


lea esi, DWORD PTR [ebp+12] 

sub esp, ecx 

mov edi, esp 

rep movsb 


; thunk to the 16-bit function 
; convert returned address 


; — save the registers — 

; push stack frame 
; set new stack frame 
; save the ebx register 

; save the edi register 

; save the esi register 

; save the es register 

; save current 32-bit stack 
; save the ss register 
,■ save the stack pointer 

; --- copy the parameters --- 

; parameters are at ebp+12- 

; ecx contains size of parms 
; set source address 
; copy the parameters 

; --- convert stack to 16:16 
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mov eax, esp 

ror eax, 16 

shl ax, BYTE PTR 3 

or al, 7 

rol eax, 16 

push eax 

lss sp, DWORD PTR [esp] 
movzx esp,sp 


jmp FAR PTR _CALL_THUNK 

CALL_THUNK_RETURN: 
shl eax, 16 

shrd eax,edx,16 

movzx esp, sp 

lss esp, FWORD PTR [esp] 

pop es 

pop esi 

pop edi 

pop ebx 

leave 
ret 

_D0_THUNK ENDP 

TEXT32 ENDS 


; copy current stack pointer 
; swap high and low word 
; shift left 3 bits 
; add in the 3 low bits 
; swap high and low word back 
; push 16:16 stack pointer 
; convert stack 
; insure high word is 0 

; --- call the 16:16 function 
; jump to 16-bit segment 

; return value in ax and dx 
; shift low word of return 
; shift high and low word 
; insure high word is 0 
; convert stack back 
; restore the es register 

; restore the esi register 

; restore the edi register 

; restore the ebx register 


16-BIT CODE SEGMENT 


_TEXT16 SEGMENT WORD USE16 PUBLIC 'CODE' 

_CALL_THUNK PROC FAR 

call DWORD PTR [bp+8] ; call 16:16 function 

jmp FAR PTR FLAT:_CALL_THUNK_RETURN 
_CALL_THUNK ENDP 

_TEXT16 ENDS 

END 


If you are not an expert in assembler code, this code may seem overwhelming. How¬ 
ever, it provides a core to performing all your thunks, and with minor modifications, 
new thunks can be created. We will be using the functions D0S32FLATT0SEL and 
D0S32SELT0FLAT to do all our address conversion: 

_TEXT32 SEGMENT DWORD USE32 PUBLIC 'CODE 1 

EXTRN Dos32FlatToSel:NEAR 
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EXTRN Dos32SelToFlat:NEAR 
TEXT32 ENDS 


Each of the 16-bit functions to be called must be declared as external functions within 
a 16-bit code segment. We name our 16-bit segment _TEXT 16: 

_TEXT16 SEGMENT WORD USE16 PUBLIC 'CODE' 

EXTRN GetBooklnformation:FAR 

EXTRN GetAuthorBylndex:FAR 
TEXT16 ENDS 


In the _THUNK_GetBookInf ormation thunk, each parameter must be pushed onto 
the stack using word alignment. This requires nothing more than pushing the appropri¬ 
ate size parameter onto the stack. All parameters must be pushed in the order the 16-bit 
function is expecting. Usually this follows the Pascal calling convention in which param¬ 
eters are pushed from left to right. The parameters from the application start at address 
[ ebp+8] . This function is passing the address of a structure, so it must be converted: 


mov eax, DWORD PTR [ebp+8] 

call Dos32FlatToSel 
push eax 


- - - push function parameters 
move 1st parameter to eax 
convert from 32-bit to 16:16 
push 1st parameter (16:16) 


The address of the 16-bit function is pushed after all parameters have been pushed: 

; --- push 16-bit function 
mov eax, SEG GetBooklnformation 

shl eax, 16 

or eax, OFFSET GetBooklnformation 

push eax 


Our generic thunk function _D0_THUNK requires that the total number of bytes taken 
up by the actual parameters of the function be placed in the ecx register. For this func¬ 
tion, it is four bytes (in other words, sizeof (PBOOKINFORMATION)). Upon return from 
the _D0_THUNK call, we must handle the case in which we have an address returned within 
a structure pointed to by our parameter. We first load the address of the structure and 
then get the address of the field within the structure. It is then converted and replaced in 
the structure: 


mov ecx, DWORD PTR [ebp+8] ; move address of structure to ecx 

mov eax, DWORD PTR [ecx+2] ; move address of field to eax 

call Dos32SelToFlat ; convert structure field address 

mov DWORD PTR [ecx+2], eax ; move back info structure field 

The GetAuthorBylndex function begins by pushing a USHORT value onto the stack. 
This is required because the 16-bit function is expecting only two bytes to be taken up 
on the stack by this parameter: 


push WORD PTR [ebp+8] 


; — push function parameters 
; push 1st parameter (uslndex) 
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Again the address of the function is pushed on the stack after the parameters have 
been pushed and the total size of the actual parameters (two) is set into the ecx register. 
This time on return from the _DO_THUNK call, the return value is a pointer. Because the 
return value is already in the eax register, we can just call Dos32SelToFlat: 

call Dos32SelToFlat ; convert returned address 

The _D0_THUNK code begins by saving all the necessary registers. Because the pa¬ 
rameters no longer start at esp as a result of pushing these registers, we must copy the 
parameters again. Note at this point that you can avoid copying the parameters again if 
you choose to write a complete thunk for each 16-bit function to call. A complete thunk 
would include combining the thunk entry function and the _D0_THUNK function. We 
have traded off the overhead of copying the parameters with the simplicity of a single 
thunk worker function. The parameters start at ebp+1 2 , and we use the size that was set 
into the ecx register to tell us how many bytes to copy: 

; — copy the parameters - - - 
lea esi, DWORD PTR [ebp+12] ; parameters are at ebp+12 

sub esp, ecx ; ecx contains size of parms 

mov edi, esp ; set source address 

rep movsb ; copy the parameters 

The stack registers are then converted from 32-bit to 16-bit, and we jump into a 16- 
bit code segment to make the call. We must make the call from a 16-bit code segment 
because attempting to call a 16-bit function from a 32-bit function will fail: 

_TEXT16 SEGMENT WORD USE16 PUBLIC 'CODE' 

_CALL_THUNK PROC FAR 

call DWORD PTR [bp+8] ; call 16:16 function 

jmp FAR PTR FLAT:_CALL_THUNK_RETURN 
_CALL_THUNK ENDP 

_TEXT16 ENDS 

Upon return from the 16-bit function, we jump back into the 32-bit code segment 
at address _CALL_THUNK_RETURN. The return value is then loaded into eax; the registers 
are restored; and we return to the thunk entry function. 

You can now take this code and create your own thunks. To change this code or to 
create your own follow these steps: 

1. Define the 16-bit function as extern within the 16-bit code segment, for 
example: 

_TEXT16 SEGMENT WORD USE16 PUBLIC 'CODE' 

EXTRN GetBooklnformation:FAR 
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_TEXT16 ENDS 

2. Provide a public thunk entry function, for example: 

PUBLIC _THUNK_GetBookInformation 

3. Define the thunk entry function and push all parameters. Remember to convert 
all addresses to 16:16 addresses. 

4. Push the address of the 16-bit function. 

5. Set ecx to the total size of your actual parameters. 

6. Upon return from the _D0_THUNK call, convert any returned addresses back to 
32-bit addresses. 

The thunk code contained in THUNKASM.ASM does not handle the case where 
the 32-bit stack register is approaching a 64K boundary when the call into the 16-bit 
code is made. The stack for the 16-bit stack, when called through our thunk, is limited 
to the amount of space remaining within the 64K boundary. This may or may not be 
a problem with your code. To compensate for this potential problem, code must be 
inserted in the thunk to check that the 32-bit stack register is not within 4K of a 64K 
boundary. This must be done prior to pushing the parameters onto the stack. If the stack 
register is within 4K of the 64K boundary, it must set the current stack pointer to the top 
of the next 64K boundary below the current stack pointer. Remember to reset the cur¬ 
rent stack pointer upon return from calling the 16-bit code. 
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book itself. Instead we will focus on the API available for communications. Further in¬ 
formation on the low-level details can be found in the OS/2 Physical Device Driver ref¬ 
erence manual. 


Features of OS/2 Communications 

As its name implies, asynchronous communications occurs asynchronously to other ac¬ 
tivities in the system. In other words, the events of communications may happen at any 
moment. They are not limited to specific intervals; they cannot be timed. Data is trans¬ 
mitted and received by the ASYNC device driver as part of the normal operation of 
OS/2 and occurs while other activities and applications are executing. The driver coordi¬ 
nates requests to send and receive data from the applications. Because we are running in 
a multitasking environment and the system must deal with hardware interrupts, it is not 
always possible for the hardware to be ready when a request to send data occurs. Like¬ 
wise, the hardware may receive data from the remote connection when the application is 
not ready to receive it. 

To support these contingencies, the driver makes use of a transmit queue and a re¬ 
ceive queue. The transmit queue is used to buffer the data sent from the application for 
which data has not yet been transmitted or sent to the physical hardware. To buffer data 
means that it is stored in a sequential manner until the facility is available to send it or act 
on it. The receive queue is used to buffer the data received from the physical hardware 
that has not yet been requested from the application. The driver is responsible for coor¬ 
dinating the flow of data through these buffers and talking with the physical hardware. 

We can illustrate the flow of data in both directions. When an application wants to 
transmit data, it makes a call to the ASYNC device driver to send the data. As shown in 
Figure 14.1, the driver places the data into the transmit queue. 


Figure 14.1. 
Transmit queue 
data buffer. 


Application 


"Hello" 


ASYNC device driver 


transmit queue 


"Hello" 


send- 
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Figure 14.2 illustrates the hardware’s retrieval of data from the transmit queue. When 
the hardware signals the driver that it is ready to transmit, the driver then hands off the 
data to the hardware. 




Communications Basics 


Chapter 


Figure 14.2. 
Transmit queue 
data retrieval. 
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Just the opposite activity occurs when data is received by the device driver. Fig¬ 
ure 14.3 illustrates the hardware copying the data into the receive queue. When the hard¬ 
ware receives data, it signals the ASYNC device driver that data has been received and is 
ready to be retrieved. The driver places the data into the receive queue. 


Figure 14.3. 
Receive queue 
data buffering. 


ASYNC device driver 
receive queue 
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When the application requests data from the ASYNC device driver, the driver satis¬ 
fies the request by moving the data from the receive queue to the application. Figure 14.4 
illustrates this process. 

Figure 14.4. ASYNC device driver 

Receive queue data 

retrieval. Application receive queue 
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"Good-Bye" --receive 
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The ASYNC device driver is capable of supporting multiple communications ports 
at the same time. Each port has its own set of transmit and receive buffers. The ASYNC 
device driver also supports a feature called Extended Hardware Buffering. This is a fea¬ 
ture of the hardware that allows the hardware to buffer data itself and only send the buffer 
when a hardware interrupt occurs. Normally, the hardware operates in character mode 
whereby the hardware services one character at a time. Transmission and receipt of each 
character requires separate interrupts. This requires quite a bit of overhead for the hard¬ 
ware. With Extended Hardware Buffering, the hardware can send multiple characters 
with a single interrupt. This can significantly reduce the number of interrupts that must 
occur and improve the throughput of the data. 

As coordinator of all communication activities between the application and hardware, 
it is the responsibility of the ASYNC driver to manage the flow of data and monitor vari¬ 
ous events. There are several hardware settings and states of flow control that can be set 
by an application. 

Hardware Settings 

There are a number of terms used for data communications. It is necessary to understand 
their meaning in order to work with communications effectively. 

The baud rate refers to the rate at which data is transferred. This value is specified in 
bits per second (bps) and must match the current speed setting of the hardware device. 
Examples of the baud rate are 1,200 bps and 2,400 bps. 

The data bits specify the number of bits that contain data in each character trans¬ 
ferred. Valid values are 5 through 8. 

The stop bits specify the number of bits that are used to separate each character. Valid 
values are 1, 1.5, and 2. 

Parity refers to the type of parity checking performed on the data. Parity checking is 
used to check that the data is transferred successfully and that no data has been lost. Valid 
values are none, even, odd, mark, and space. 

Read timeout enabling allows you to indicate how long to wait when requesting data 
from the driver. There are three options. If a request is made to read data and there is no 
data available, the request can fail immediately and return. This is called no-wait read 
timeout. Using this timeout, your application is not forced to wait around for data to 
appear. If the same request is made and no data is available within a specified amount of 
time, the request fails and returns. This is called normal read timeout. Finally, if the re¬ 
quest is made but it should not return until some data is available, this is called wait-for - 
something timeout. Wait-for-something timeout can return without any data, but only 
after a specified period of time. 
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Write timeout is similar to read timeout except it refers to the amount of time to wait 
for the driver to transmit the data sent to it. If the driver sends data to the hardware and 
should wait until all data is transmitted, then it is called infinite timeout. If the driver 
should only wait on the hardware for a specified time and return even if all data has not 
been transmitted, it is referred to as normal timeout. 

All timeout periods are specified in hundredths of a second. 

Flow Control 

Flow control determines how the ASYNC driver behaves when the receive and transmit 
queues contain a certain level of data. When Receive Flow Control is enabled, the driver 
will send an XOFF character when the receive queue is nearly full. This tells the remote 
driver to cease transmitting data until it receives the XON character. 

When the receive queue drops back down to about half full, it transmits the XON 
character, which tells the remote driver that it is okay to transmit more data. When Trans¬ 
mit Flow Control is enabled, the driver responds to the XOFF and XON characters by 
suspending the transmission of data when it receives the XOFF character and resuming 
transmission when it receives the XON character. It is still possible for an application to 
transmit data when the driver has received the XOFF character and is not currently 
transmitting. The application can perform a “transmit immediate” operation, which forces 
the character to be sent. 

It is possible for an error to occur during the transmission of data. Examples of errors 
are parity errors caused by a noisy transmission line. Another error is a full receive queue. 
If error replacement character processing is enabled, the driver will substitute all charac¬ 
ters in error with an error replacement character. 

When the driver detects a break condition on the line, it can likewise notify the 
application. If break replacement character processing is enabled, the driver will notify 
the application by inserting the specified break character into the receive queue. 

The driver can also filter out null characters (0x00). This is called null stripping. When 
null stripping is enabled, all null characters that the driver receives are thrown away. 

Communicating with 
the ASYNC Device Driver 

Before using the ASYNC device driver, it must be installed when your system boots. The 
driver is installed by placing the appropriate DEVICE statement in the CONFIG.SYS file: 

DEVICE=C:\0S2\C0M.SYS 


721 



Real-World Programming for 


OS/2 2.1 


A communications port, COM2 for example, is opened just as any other file is opened. 
Use the DosOpen function to open a file named COMx, where x is the number of the 
communications port. To open the COM2 port, for example, issue the following call: 

HFILE hFile; 

ULONG ulAction; 

DosOpen ("COM2", &hFile, &ulAction, 0L, FILE_NORMAL, FILE_0PEN, 
OPEN_ACCESS_READWRITE j OPEN_SHARE_DENYNONE, 0L); 

Notice that the access mode of OPEN_SHARE_DENYNONE allows multiple processes to 
share the communications port. To prevent other processes from opening the same com¬ 
munications port, use OPEN_SHARE_DENYREADWRITE. To write data out of the commu¬ 
nications port, use the DosWrite function; to read data, use the DosRead function. When 
communications is complete and you want to terminate use of the port, call the DosClose 
function. You can see how similar this operation is to working with files. 

The DosDevIOCtl Function 

When the port has been opened and a file handle returned, an application can commu¬ 
nicate with the ASYNC device driver via the DosDevIOCtl function. The DosDevIOCtl 
function contains many subfunctions that specify the particular action for the device driver 
to perform. 

This is one of the more confusing functions to use in OS/2. It can be used for inter¬ 
action with the serial port, as well as the video driver, keyboard, mouse, and other things. 
As you might imagine, given that it can be used with so many different subsystems, the 
structure of the input and output parameters for the function is generic. Take a look at 
the function definition below. The first three parameters are easily understood. They are 
a handle to a device, the category of subfunction, and the specific function within that 
category. In our case here, the only functions with which we are concerned are those that 
involve the serial port. These are category 01. Within this category are 27 other 
subfunctions that govern serial communications. The confusing part is the generic means 
needed for input and output parameters for all the possible subfunctions: 

The particulars of the DosDevIOCtl function are listed below: 

APIRET APIENTRY DosDevIOCtl(HFILE hDevice, ULONG category, ULONG 
function, PVOID pParams, ULONG cbParmLenMax, 

PULONG pcbParmLen, PVOID pData, ULONG cbDataLenMax, 
PULONG pcbDataLen) 

Parameter Descriptions: 


Parameter 

hDevice 


Description 

File handle returned from DosOpen. 
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category 


pParams 

cbParmLenMax 

pcbParmLen 


pData 

cbDataLenMax 

pcbDataLen 


Device category. 

IOCTL_ASYNC—Asynchronous Device 
Support function—Device function. There 
are others, but this is the only one with 
which we are concerned here. 

Input parameter list for function. 
Maximum length of data in pParams. 
Pointer to variable to receive 
length of return parameters in 
pParams. 

Pointer to output data area. 

Maximum length of data in pData. 

Pointer to variable to receive 
length of return parameters in 
pData. 


Let’s make a quick rundown of each of the IOCTL_ASYNC functions and the param¬ 
eters specified for each. 


ASYNC_SETBAUDRATE—Set Baud Rate 

Input data: 

USHORT—Baud rate 
Example: 

USHORT usBaudRate = 1200; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETBAUDRATE, 

(PVOID)&usBaudRate, sizeof(USHORT), NULL, NULL, 0L, NULL); 

ASYNC_SETLINECTRL—Set Line Characteristics 

Input data: 

LINECONTROL—Line control information. This is the structure: 
typedef struct _LINECONTROL 

Its fields and the allowable values are listed below: 


BYTE 

bDataBits 

0x05 

5 data bits 

0x06 

6 data bits 

0x07 

7 data bits 

0x08 

8 data bits 
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BYTE 

0x00 

0x01 

0x02 

0x03 

0x04 


h Parity’ 

None 

Odd 

Even 

Mark 

Space 


BYTE 

0x00 

0x01 

0x02 


hStopBits 

1 stop bit 
1.5 stop bits 

2 stop bits 


BYTE fTransBreak 

0x00 No break character transmitted. 

0x01 Transmit break character. 


Example: 


LINECONTROL LineControl; 
LineControl.bDataBits = 8; 

LineControl.bParity = 0x00; 

LineControl.bStopBits = 0x00; 

LineControl.fTransBreak = 0x01; 

DosDevIOCtl (hFile, I0CTL_ASYNC, 


/* 8 data bits */ 

/* Parity None */ 

/* 1 stop bit */ 

/* Transmit break */ 
ASYNC_SETLINECTRL, 


&LineControl, sizeof(LINECONTROL), NULL, NULL, 0L, NULL); 


ASYNC_TRANSMITIMM—Transmit Byte Immediate 

Input Data: 

CHAR—Character to transmit 
Example: 

CHAR ch = 'X'; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_TRANSMITIMM, 

&ch, sizeof(CHAR), NULL, NULL, 0L, NULL); 

ASYNC_SETBREAKOFF—Turn Off Break Character 

Output Data: 

USHORT—Communications error flags 

RX_QUE_OVERRUN Receive queue is full. 

RX_HARDWARE_OVERRUN New character received before 

last character processed. New 
character is lost. 
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PARITY_ERROR Parity error detected. 

FRAMING_ERROR Framing error detected. 

Example: 

USHORT usComError; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETBREAKOFF, 

NULL, 0L, NULL, (PVOID)&usComError, sizeof(USHORT), NULL); 


ASYNC_SETMODEMCTRL—Set the Modem 
Control Signals 

Input Data: 

MODEMSTATUS—Modem control masks 
This is the structure: 


typedef struct _MODEMSTATUS 

Its fields and allowable values are listed below: 


B YTE fbModem On 

DTR_ON 

RTS_ON 


Specifies Flags to Turn On 
Set DTR flag 
Set RTS flag 


BYTE fbModemOjf 

DTR_OFF 

RTS.OFF 


Specifies Flags to Turn Off 
Clear DTR flag 
Clear RTS flag 


Note: If both DTRJ3N and DTRJ3FF are specified, the flag is turned on. If both RTS__ON 
and RTS_0FF are specified, the flag is turned on. 


Output Data: 

USHORT— Communications error flags 

The following flags are valid: 

RX_QUE_OVERRUN 

RX_HARDWARE_OVERRUN 


PARITYJERROR 

FRAMING_ERROR 


Receive queue is full. 

New character received before 
last character processed. New 
character is lost. 

Parity error detected. 

Framing error detected. 
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Example: 

MODEMSTATUS ModemStatus; 

USHORT usComError; 

ModemStatus.fbModemOn = DTR_ON \ RTS_ON; 

ModemStatus.fbModemOff = 0; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETMODEMCTRL, 

(PVOID)&ModemStatus, sizeof(MODEMSTATUS), NULL, 
(PVOID)&usComError, sizeof(USHORT), NULL); 

ASYNC_SETBREAKON—Turn On Break Character 

Output Data: 

USHORT—Communications error flags 

The following flags are valid: 

RX_QUE_OVERRUN 
RX_HARDWARE_OVERRUN 

PARITYJERROR 
FRAMINGJERROR 

Example: 

USHORT usComError; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETBREAKON, 

NULL, 0L, NULL, (PVOID)&usComError, sizeof(USHORT), NULL); 

ASYNC_STOPTRANSMIT—Turn Off Transmission 
(XOFF Received) 

Example: 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_STOPTRANSMIT, 

NULL, 0L, NULL, NULL, 0L, NULL); 

ASYNC_STARTTRANSMIT —Turn On Transmission 
(XON Received) 

Example: 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_STARTTRANSMIT, 

NULL, 0L, NULL, NULL, 0L, NULL); 


Receive queue is full. 

New character received before 
last character processed. New 
character is lost. 

Parity error detected. 

Framing error detected. 
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ASYNC_SETDCBINFO—Set Device Control Block 
Information 

Input Data: 

DCBINFO—Device control block information 
This is the structure: 
typedef struct _DCBINF0 


It has the following fields and defined values: 


USHORT 

usWriteTimeout 

Write timeout time period 
(hundredths of a second). 

USHORT 

usReadTimeout 

Read timeout time period 
(hundredths of a second). 

BYTE 

fbCtlHndShake 

Specifies control and 
handshaking modes: 


MODE_DTR_CONTROL 

Enable DTR Control 

Mode. 


MODE_DTR_HANDSHAKE 

Enable DTR Control input 
handshaking. 


MODE_CTS_HANDSHAKE 

Enable CTS output 
handshaking. 


MODE_DSR_HANDSHAKE 

Enable DSR output 
handshaking. 


MODE_DCD_HANDSHAKE 

Enable DCD output 
handshaking. 


MODE_DSR_SENSITIVTTY 

Enable DSR input 
sensitivity. 


Note: MODE_DTR__CONTROL and MODE__DTR_HANDSHAKE cannot be specified together. 

BYTE fbFlowReplace Specifies flow control and 

replacement character 
modes: 

MODE_AUTO_TRANSMIT Enable auto transmit flow 

control (XON and XOFF). 

MODE_AUTO_RECEIVE Enable auto receive flow 

control (XON and XOFF). 

MODE_ERROR_CFIAR Enable error replacement 

character. 
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BYTE 


BYTE 


fbFlowReplace 

Specifies flow control 
and replacement 
character modes: 

MODE_NULL_STRIPPING 

Enable null stripping. 

MODE_BREAK_CHAR 

Enable break replace¬ 
ment control (XON 
and XOFF). 

0x20 

Enable full duplex flow 
control. 

MODE_RTS_CONTROL 

Enable RTS control 
mode. 

MODE_RTS_HANDSHAKE 

Enable RTS input 
handshaking. 

MODE_TRANSMIT_TOGGLE 

Toggle RTS on 
transmit. 

fbTimeout 

Specifies timeout 
process for device: 

MODE_NO_WRITE_TIMEOUT 

Enable write infinite. 

MODE_READ_TIMEOUT 

Enable normal read. 

MODE_WAIT_READ_TIMEOUT 

Enable wait-for- 
something read. 

MODE_NOWAIT_READ_TIMEOUT 

Enable no-wait read. 

0x08 

Disable extended 
hardware buffering. 

0x10 

Enable extended 
hardware buffering. 

0x18 

Automatic protocol 
override. 

0x20 

Extended buffer size of 
4 characters. 

0x40 

Extended buffer size of 
8 characters. 

0x60 

Extended buffer size of 
16 characters. 

0x80 

Transmit buffer size 
of 16 characters. 


Notes Extended buffer size is 1 character unless otherwise specified. Transmit buffer 
size is 1 character unless otherwise specified. 
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BYTE 

bErrorReplacementChar 

Character inserted 
when character in error 
received. 

BYTE 

bBreakReplacementChar 

Character inserted 
when break detected in 
line. 

BYTE 

bXONChar 

Character used for 
XON signal. 

BYTE 

bXOFFChar 

Character used for 
XOFF signal. 


Example: 

DCBINFO DCBInfo; 

DCBInfo.usWriteTimeout = 0; 

DCBInfo.usReadTimeout = 0; 

DCBInfo.fbCtlHandShake = M0DE_DTS_C0NTR0L; 

DCBInfo.fbFlowReplace = 0; 

DCBInfo.fbTimeout = M0DE_N0_WRITE_TIME0UT | MODE_READ_TIMEOUT; 


DCBInfo.bErrorReplacementChar = '\0 1 
DCBInfo.bBreakReplacementChar = 1 \0' 
DCBInfo.bXONChar = 0x11 
DCBInfo.bXOFFChar = 0x13 


DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETDCBINFO, 

&DCBInfo, sizeof(DCBINFO), 0L, NULL, 0L, NULL); 

ASYNC_GETBAUDRATE—Query the Baud Rate 

Output Data: 

USHORT—Baud rate 

Example: 

USHORT usBaudRate; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETBAUDRATE, 

NULL, 0L, 0L, (PVOID)&usBaudRate, sizeof(USHORT), NULL); 

ASYNC_GETLINECTRL -—Query Line Characteristics 

Output data: 

LINECONTROL—Line control information 
This is the structure: 
typedef struct _LINECONTROL 

It has the following fields and allowable values: 
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BYTE 

bDataBits 

0x05 

5 data bits 

0x06 

6 data bits 

0x07 

7 data bits 

0x08 

8 data bits 

BYTE 

bParity 

0x00 

None 

0x01 

Odd. 

0x02 

Even 

0x03 

Mark 

0x04 

Space 

BYTE 

b Stop Bits 

0x00 

1 stop bit 

0x01 

1.5 stop bits 

0x02 

2 stop bits 

BYTE 

fl\ransBreak 

0x00 

No break character transmitted. 

0x01 

Transmit break character. 


Example: 

LINECONTROL LineControl; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETLINECTRL, 

NULL, 0L, 0Lj (PVOID)&LineControl, sizeof(LINECONTROL), 0L); 


ASYNC_GETCOMMSTATUS—Get Communication Status 
Flags 

Output Data: 

BYTE—Communications status flags 


The following flags are defined: 

TX_WAITIN G_F O R_CT S 
TX_WAITING_FOR_DSR 
TX_WAITIN G_F O R_DCD 

TX_WAITING_FOR_XON 

TX_WAITING_TO_SEND_XON 


Transmit waiting for CTS signal. 
Transmit waiting for DSR signal. 
Transmit waiting for DCD 
signal. 

Transmit waiting because XOFF 
character was received. 

Transmit waiting because XOFF 
character was transmitted. 
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TX_WA1TING_WHILE_BREAK_ON Transmit waiting because break 

character is being transmitted. 
TX_WAITING_TO_SEND_IMM Transmit waiting to send the 

character immediately. 

RX_WAITING_FOR_DSR Receive waiting for DSR signal. 

Example: 

BYTE CommStatus; 

DosDevIOCtl (hFilej IOCTL_ASYNC, ASYNC_GETCOMMSTATUS, 

NULL , 0L 3 0L, (PVOID)&CommStatus, sizeof(BYTE), NULL); 

ASYNC_GETLINESTATUS —Query Data 
Transmission Status 

Output Data: 

BYTE—Transmission status flags 

WRITEJREQUEST_QUEUED 

DATA_IN_TX_QUE 
HARDWARE_TRANSMITTING 

CHAR_READY_TO_SEND_IMM 

WAITIN G_T 0_SEND_X0N 

WAITIN G_T 0_S END_XOFF 

Example: 

BYTE LineStatus; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETLINESTATUS, 

NULL, 0L, 0L, (PVOID)&LineStatus, sizeof(BYTE), NULL); 

ASYNC_GETMODEMOUTPUT—Query Modem Control 
Output Status 

Output Data: 

BYTE—Modem output status flags 

The following flags are defined: 

DTR signal is on (Data-Terminal-Ready). 

RTS signal is on (Request-To-Send). 


Write request in progress or 
queued. 

Data exists in transmit queue. 
Hardware current transmitting 
data. 

Character ready to be 
transmitted immediately. 
Waiting to transmit XON 
(automatically). 

Waiting to transmit XOFF 
(automatically). 


DTR_ON 

RTS_ON 
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Example: 

BYTE ModemOutputFlags; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMOUTPUT, 

NULL, 0L, 0L, (PVOID)&ModemOutputFlags, sizeof(BYTE), NULL); 

ASYNC_GETMODEMINPUT—Query Modem Control 
Input Status 

Output Data: 

BYTE—Modem input status flags 

The following flags are defined: 

CTS_ON CTS signal is on. 

DSR_ON DSR signal is on. 

RI_ON RI signal is on. 

DCD_ON DCD signal is on 

Example: 

BYTE ModemlnputFlags; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMINPUT, 

NULL, 0L, 0L, (PVOID)&ModemInputFlags, sizeof(BYTE), NULL); 

ASYNC_GETINQUECOUNT—Query Number of 
Characters in Receive Queue 

Output Data: 

RXQUEUE—Receive queue information 

This is the structure: 

typedef struct _RXQUEUE 

It has the following fields and allowable values: 

USEIORT cch Number of characters in the receive queue. 

USHORT cb Size of the receive queue. 

Example: 

RXQUEUE ReceiveQueue; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETINQUECOUNT, 

NULL, 0L, 0L, (PVOID)&ReceiveQueue, sizeof(RXQUEUE), NULL); 


(Clear-To-Send) 

(Data-Set-Ready) 

(Ring-Indicator) 

(Data-Carrier- 

Detect) 


732 




Chapter Communications Basics 


ASYNC_GETOUTQUECOUN— Query Number of 
Characters in Transmit Queue 

Output Data: 

RXQUEUE—Transmit queue information 

This is the structure: 

typedef struct _RXQUEUE 

It has the following fields and allowable values: 

USHORT cch Number of characters in the transmit queue. 

USHORT cb Size of the transmit queue. 

Example: 

RXQUEUE TransmitQueue; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETINQUECOUNT, 

NULL 3 0L 3 0L, (PVOID)&Transmit, sizeof(RXQUEUE), NULL); 

ASYNC_GETCOMMERROR— Query Communications 
Error Flags 

Output Data: 

USHORT—Communications error flags 

The following flags are defined: 

RX_QUE_OVERRUN 
RX_HARDWARE_OVERRUN 

PARITYJERROR 
F RAMIN G_ERRO R 

Example: 

USHORT usCommError; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMERROR, 

NULL, 0L, NULL, (PVOID)&usCommError, sizeof(USHORT), NULL); 

ASYNC_GETCOMMEVENT— Query Communications 
Event Flags 

Output Data: 

USHORT—Communications event flags 


Receive queue is full. 

New character received before 
last character processed. New 
character is lost. 

Parity error detected. 

Framing error detected. 




Real-World Frogramming 


for OS/2 2.1 


The following flags are defined: 

CHAR_RECEIVED 

0x02 

LAST_CHAR_SENT 
CT S_CHAN GED 
DSR_CHANGED 
D CD_CHAN GED 
BREAK_DETECTED 
ERROR_OCCURRED 

RI_DETECTED 


Character placed into receive queue. 
Receive timeout occurred during read. 
Last character in transmit queue sent. 
CTS signal has changed state. 

DSR signal has changed state. 

DCD signal has changed state. 

Break in the line has been detected. 
Parity, framing, or queue overrun 
error occurred. 

Trailing edge of ring indicator 
detected. 


Example: 

USHORT usCommEvent; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMEVENTj 

NULL, 0L, 0L, (PVOID)&usCommEvent, sizeof(USHORT), NULL); 


ASYNC_GETDCBINFO—Query Device Control Block 
Information 

Output Data: 

DCBINFO—Device control block information 
This is the structure: 


typedef struct _DCBINF0 

It has the following fields and allowable values: 
USHORT usWriteTimeout 

USHORT usReadTimeout 

BYTE fbCtlHndShake 

MODE_DTR_CONTROL 

MODE_DTR_HANDSHAKE 

MODE_CTS_HANDSHAKE 


Write timeout time period 
(hundredths of a second). 
Read timeout time period 
(hundredths of a second). 
Specifies control and hand¬ 
shaking modes: 

DTR Control Mode 
enabled. 

DTR Control input 
handshaking enabled. 

CTS output hand¬ 
shaking enabled. 



BYTE 


BYTE 
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MODE_DSR_HANDSHAKE 

DSR output hand¬ 
shaking enabled. 

MODE_DCD_HANDSHAKE 

DCD output hand¬ 
shaking enabled. 

MODE_DSR_SENSITIVITY 

DSR input sensitivity 
enabled. 

fbFlowReplace 

Specifies flow control 
and replacement 
character modes: 

MODE_AUTO_TRANSMIT 

Auto transmit flow 
control (XON and 
XOFF) enabled. 

MODE_AUTO_RECEIVE 

Auto receive flow 
control (XON and 
XOFF) enabled. 

MODE_ERROR_CHAR 

Error replacement 
character enabled. 

MODE_NULL_STRIPPING 

Null stripping 
enabled. 

MODE_BREAK_CHAR 

Break replacement 
control (XON and 
XOFF) enabled. 

0x20 

Full duplex flow 
control enabled. 

MODE_RTS_CONTROL 

RTS control mode 
enabled. 

MODE_RTS_HANDSHAKE 

RTS input handshak¬ 
ing enabled. 

MODE_TRANSMIT_TOGGLE 

Toggle RTS on 
transmit. 

fbTimeout 

Specifies timeout 
process for device: 

MODE_NO_WRITE_TIMEOUT 

Write infinite enabled. 

MODE_READ_TIMEOUT 

Normal read enabled. 

MODE_WAIT_READ_TIMEOUT 

Wait-for-something 
read enabled. 

MODE_NOWAIT_READ_TIMEOUT 

No-wait read enabled. 

0x08 

Extended hardware 
buffering disabled. 
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0x10 

Extended hardware buff¬ 
ering enabled. 


0x18 

Automatic protocol over¬ 
ride. 


0x20 

Extended buffer size of 

4 characters. 


0x40 

Extended buffer size of 

8 characters. 


0x60 

Extended buffer size of 

16 characters. 


0x80 

Transmit buffer size of 

16 characters. 

BYTE 

bErrorReplacementChar 

Character inserted when 
character in error received. 

BYTE 

bBreakReplacementChar 

Character inserted when 
break detected in line. 

BYTE 

bXONChar 

Character used for XON 
signal. 

BYTE 

bXOFFChar 

Character used for XOFF 
signal. 


Example: 

DCBINFO DCBInfo; 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETDCBINFO, 

NULL, 0L, 0L, (PVOID)&DCBInfo, sizeof(DCBINFO), NULL); 

Phone Application 

The application for this chapter demonstrates both the transmission and receipt of data 
through one of the communication ports. It also makes use of multiple threads and event 
semaphores. Because we are dealing with asynchronous events on the communications 
port, we never know exactly when we will be receiving data or possibly even when data is 
being transmitted. For that reason, we will establish a receive data thread. This way the 
application is not forced to wait around for data, keeping the user on hold. The 
application can continue processing and interacting with the user even though no data is 
immediately available. We will also establish a communications status thread that will 
constantly poll the various status and update the flags in the window. 

The phone application will have two data viewing areas: a local connection area and 
remote connection area. These windows are shown in Figure 14.5- The local connection 
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area will consist of an entry window and a history window. The entry window will be 
used to enter text to be transmitted. The history window will contain a list of the last 100 
lines of transmitted text. The remote connection area will consist of a display window 
and a history window. The display window will show the current line of text being re¬ 
ceived. The history window will contain a list of the last 100 lines of received text. At the 
bottom of the window will be a set of communications status LEDs. These LEDs will 
be constantly updated as the communication status flags change. 


Figure 14.5. 
Phone application 
window. 



Local Connection 


i Hanglip 


Remote Connection 


-Queue 1 -".. 
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-Comm Enof-—- i 

QGV HOV PAR FRM 


Although you can start this sample application without having the communications 
driver or a COM port installed, obviously it won’t do much. If your system has a modem 
or even a debug terminal attached, you will be able to see and do much more with this 
sample. In some ways a debug terminal is even more illustrative because you can see the 
characters going out to the debug terminal as well as those returning from the debug 
terminal’s keyboard. 

On the right side of the window are five buttons. The Connect button will attempt 
to open the communications port using the current settings. The HangUp button will 
close the currently open session. The Settings button will display a settings dialog that 
enables you to change the settings for each port. The Stop button will cause transmission 
to be stopped (XOFF). When transmission is stopped, the text of this button will change 
to Start. Pressing Start will restart transmission (XON). The Abort button displays an 
information dialog box. 
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While a session is active, you enter the text to be sent in the local entry window. Press 
Enter to transmit the line of text. Double-clicking any entry in the local history list will 
cause the text on that line to be copied to the local entry window for editing. As data is 
received from the remote site, the data is displayed in the remote display window; and 
when the carriage return is received, the line of text is moved to the remote history 
window. Pressing the Settings button will display the settings dialog box, as shown in 
Figure 14.6. 

Figure 14.6. 

The settings dialog. 


The settings dialog does not include all possible settings, but it does provide a major¬ 
ity of the possible flags. The following list describes the acronyms used in this dialog. 


RTS 

Request to Send. 

CTS 

Clear to Send. 

DSR 

Data Set Ready. 

DCD 

Carrier Detect. 

DTR 

Data Terminal Ready. 


When the application starts, it attempts to go out and retrieve the current settings 
for all of the communications ports. If it is unable to do so, it initializes the settings to 
some default settings. Selecting a port from the Port combo box will change the settings 
to reflect the port’s settings. 

You can set the desired port settings in this dialog. Notice that setting the Write and 
Read timeouts to any value other than zero will adversely impact performance as the 
DosWrite and DosRead will incur timeout processing. If you have a debug terminal 
attached to your computer, you can start a session with it using the communications 
port to which it is attached. For example, to start a TTY-like session, you might use the 
following settings: 
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Baud Rate: 9,600 

Data Bits: 8 

Stop Bits: 1 

Parity: None 

Read Timeout: 0 

Write Timeout: 0 


You should check the settings on your debug terminal for the exact values to use. 

Let s take a quick look at how the application is structured with its three threads. 
Figure 14.7 shows the three major components of the application and their interaction 
with each other. The main application will create a message queue and be known as the 
message queue thread. It will be responsible for managing the application windows and 
dialogs and for establishing the connection and writing data to the communications port. 

The receive data thread is solely responsible for reading data from the communica¬ 
tions port and notifying the main thread when there is data in the application’s receive 
buffer to be displayed. It will coordinate access to the application’s receive buffer through 
an event semaphore. 

The third thread is the communications status thread. It’s sole responsibility is to 
constantly query the communication status and notify the main thread when any of the 
sets of flags has changed. Because the receive data and communications status threads are 
not message queue threads, they cannot send messages to any windows, so all notifica¬ 
tions to the main thread are through posted messages. 


Main Thread 

We will use the CONTROLS.DLL from Chapter 10, “Dynamic Link Libraries,” which 
defines a bevel control. In addition, we define a new control called an LED control. An 
LED control is an on/off indicator with a maximum three-character text field displayed 
above the indicator. It is modeled on the lights generally found on external modems. 

The LED control is defined in LED.C, and the state is set or cleared by sending a 
WM_ENABLE message to the control. 



Real-World Programming 


for OS/2 2.1 


Figure 14.7. 
Phone application 
thread interaction. 
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LED.C 

/* 

LED Control 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


im 


/* LED Control 
Class Name 


LEDCLASS 
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Messages 

WM_ENABLE - MPFROMSHORT (enablestate) 

*/ 

#define INCL_WIN 
#define INCL_GPI 

#include <os2.h> 

#include "led.h" 

#include "phone.h" 

/* Window and Dialog Functions */ 

MRESULT EXPENTRY LEDWndProc (HWND,ULONG,MPARAM,MPARAM); 

/* Window extra bytes */ 

#define QWS_ENABLED 
#define QWL_TEXT 
#define LEDEXTRA 

/* Local Functions */ 

VOID RedrawLED (HWND,HPS,USHORT); 

/* Global Variables */ 

HBITMAP hbmLED; /* LED bitmap (contains 2 states) */ 

ULONG ulLEDCount = 0; /* Number of LED controls */ 

ULONG bmWidth; /* Width of each bitmap state */ 

ULONG bmHeight; /* Height of bitmap */ 


/* .. Local Functions . */ 

VOID RedrawLED (HWND hWnd, HPS hps, USHORT usEnabled) 

BOOL bRelease = FALSE; 

ULONG ulTxt; 

RECTL Recti; 

POINTL Ptl; 

if (!hps) 

{ 

bRelease = TRUE; 
hps = WinGetPS (hWnd); 

} 

WinQueryWindowRect (hWnd, &Rectl); 

/* Draw text with bottom 1 pel above bitmap */ 

Recti.yBottom = bmHeight + 1; 

ulTxt = WinQueryWindowULong (hWnd, QWL_TEXT); 

WinDrawText (hps, -1, (PSZ)&ulTxt, &Rectl, 0L, 0L, 

DT_CENTER | DT_BOTTOM | DT_TEXTATTRS); 



0 

QWS_ENABLED + sizeof(USHORT) 
QWL_TEXT + sizeof(ULONG) 
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/* Draw bitmap state */ 

Ptl.x = (Recti.xRight - bmWidth) » 1; 

Ptl.y = 0; 

Recti.xLeft = usEnabled ? 0 : bmWidth; 

Recti.xRight = Recti.xLeft + bmWidth; 

Recti.yBottom = 0L; 

Recti.yTop = bmHeight; 

WinDrawBitmap (bps, hbmLED, &Rectl, &Ptl, 0L, 0L, DBM_NORMAL); 

if (bRelease) 

WinReleasePS (hps); 

return; 

} 

/* .- External Function . */ 

VOID RegisterLEDClass (HAB hab) 

{ 

WinRegisterClass (hab, LEDCLASS, LEDWndProc, 0, LEDEXTRA); 
return; 

} 

/* ..Window Function .. */ 

MRESULT EXPENTRY LEDWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

RECTL Recti; 

HPS hps; 

ULONG ulText; 

PSZ pszText; 

BITMAPINFOHEADER bi; 

switch (msg) 

{ 

case WM_CREATE: 

/* Initial state is disabled */ 

WinSetWindowUShort (hWnd, QWS_ENABLED, 0); 

/* Save 3 character LED text in window extra bytes as a long */ 
pszText = ((PCREATESTRUCT)mp2)->pszText; 

ulText = (pszText[2] « 16) | (pszText[1] « 8) | pszText[0]; 
WinSetWindowULong (hWnd, QWL_TEXT, ulText); 
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/* Set font in the control */ 

WinSetPresParam (hWnd, PP_FONTNAMESIZE, FONTNAMELEN, HELV8F0NT); 

/* Load the LED bitmap when first LED control is created */ 
if (lulLEDCount) 

{ 

hps = WinGetPS (hWnd); 

hbmLED = GpiLoadBitmap (hps, 0, IDB_LED, 0L, 0L); 
GpiQueryBitmapParameters (hbmLED, &bi); 
bmWidth = bi.cx » 1; 
bmHeight = bi.cy; 

WinReleasePS (hps); 

} 

ulLEDCount++; 

break; 

case WM_ENABLE: 

WinSetWindowUShort (hWnd, QWS_ENABLED, SH0RT1FROMMP(mp1)); 

RedrawLED (hWnd, 0, SHORT1FROMMP(mp1)); 

break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 

WinFillRect (hps, &Rectl, CLR_PALEGRAY); 

RedrawLED (hWnd, hps, WinQueryWindowUShort (hWnd, QWS ENABLED))- 

WinEndPaint (hps); _ 

break; 

case WM_DESTROY: 

if (!(--ulLEDCount)) 

GpiDeleteBitmap (hbmLED); 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 


return (mReturn); 
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LED.H 

/* 

LED Control Header File 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 
.-. */ 


LED CONTROL 




#define LEDCLASS "LED" 

/* Control registration function */ 
VOID RegisterLEDClass (HAB); 


Using the LED Code 

There is not really anything new introduced by the LED control. If you have worked 
through the previous chapters in the book, the code should be fairly self-explanatory. 

The phone application itself is contained in PHONE.C. As you can see, it is a rather 
large sample application. There is a lot in this example, so we 11 just focus on the key areas 
related to communications. 

Files Required to Build the Phone Application 

The following files are required to build the phone application: 

LED.C 

LED.H 

LED.BMP 

PHONE.C 

PHONE.H 

PHONE.RC 

PHONE.DEF 

PHONE.ICO 

SETTINGS.DLG 

STATUS.DLG 

BUTTONS. DLG 

CONTROLS.DLL 
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PHONE.C 

/* 

Phone Communications Program 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 

#define INCL_D0S 

#define INCL_DOSDEVIOCTL 

#define INCL_WIN 

#define INCL_GPI 

#define INCL_ERRORS 

#include <os2.h> 

#include <stdio.h> 

#include "phone.h" 

#include ". . \common\controls.h" 

#include "led.h" 

#include ". .\common\about.h" 

/* Window and Dialog Functions */ 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY SettingsDlgProc (HWND,ULONG,MPARAM,MPARAM); 

MRESULT EXPENTRY StatusDlgProc (HWND,ULONG,MPARAM,MPARAM); 

/* Thread Functions */ 

VOID CommStatusThread (ULONG); 

VOID ReceiveDataThread (ULONG); 

/* Local Functions */ 

VOID ConnectToPort (HWND); 

VOID DelnitializeControls (HWND); 

VOID HangUpFromPort (HWND); 

VOID InitializeAppWindow (HWND); 

VOID InitializeControls (HWND,BOOL); 

VOID PositionWindows (ULONG,ULONG); 

VOID QueryBaudRate (ULONG); 

VOID QueryDCBInfo (ULONG); 

VOID QueryLineCtrl (ULONG); 

VOID QueryValidCommPorts (VOID); 

BOOL SetPortSettings (HWND); 

VOID ToggleTransmit (HWND); 

VOID TransmitLine (VOID); 

/* User-Defined messages */ 

#define WM_USER_RECEIVEQUEUE WM_USER+1 

#define WM_USER_TRANSMITQUEUE WM_USER+2 

#define WM_USER_COMSTATUS WM USER+3 
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#define WM_USER_TRANSMITSTATUS WM_USER+4 
#define WM_USER_COMEVENT WM_USER+5 

#define WM_USER_COMERROR WM_USER+6 

#define WM_USER_MODEMINPUT WM_USER+7 

#define WM_USER_MODEMOUTPUT WMJJSER+8 

#define WM_USER_RCVLIST WM_USER+9 

#define WM_USER_RCVTEXT WM_USER+10 

/* Baud Rate Information */ 
typedef struct tagBAUDRATE 
{ 

CHAR szTxt[6]; /* Text format of baud rate */ 

ULONG ulValue; /* Numeric format of baud rate */ 

} BAUDRATE; 

/* Communications Port Information */ 
typedef struct tagPORTINFO 
{ 

ULONG Baudlndex; 

ULONG BaudRate; 

DCBINFO DCBInfo; 

LINECONTROL LineControl; 

} PORTINFO; 

/* Global Variables 
HAB hab; 

HWND hWndFrame, 

hWndClient, 
hWndButtons, 
hWndStatus, 
hWndSettings, 
hWndLocalTitle, 
hWndLocalEdit, 
hWndLocalList, 
hWndLocalBevell, 
hWndLocalBevel2, 
hWndRemoteTitle, 
hWndRemoteText, 
hWndRemoteList, 
hWndRemoteBevell, 
hWndRemoteBevel2; 

CHAR szTitle[64]; 

TID StatusThreadID; 

TID ReadThreadID; 

HEV hevRcvQueue; 

HFILE hFile; 

CHAR szCom[5] 

PORTINFO Portlnfo[4]; 

ULONG ulPort 

ULONG ulNumPorts 
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BOOL 

bConnected = FALSE; 

/* 

Communications 

; currently open 

*/ 

BOOL 

bTransmitting = TRUE; 

/* 

Data transmission enabled 

*/ 

CHAR 

szReceiveBuffer[255]; 

/* 

Receive Queue 

buffer 

*/ 

USHORT 

usNextPos = 0; 

/* 

Next char pos 

in receive queue 

*/ 

ULONG 

ulNumLocalLines = 0L, 

/* 

# of lines in 

Local listbox 

*/ 


ulNumRemoteLines = 0L; 

/* 

# of lines in 

Remote listbox 

*/ 


/* Current line and status flags */ 
RXQUEUE ReceiveQueue = { 0, 0 }; 

RXQUEUE TransmitQueue = { 0, 0 }; 

BYTE ComStatus = 0; 

BYTE TransmitStatus = 0; 

USHORT ComEvent = 0; 

USHORT ComError = 0; 

BYTE Modemlnput = 0; 

MODEMSTATUS ModemOutput = { 0, 0 }; 

/* Baud Rate Table */ 

BAUDRATE BaudRates[13] = 


{ 

"110", 

110L 

}. 

{ 

"150", 

150L 

}, 

{ 

"300", 

300L 

>, 

{ 

"600", 

600L 

}, 

{ 

"1200", 

1200L 

}, 

{ 

"1800", 

1800L 

>, 

{ 

"2000", 

2000L 


{ 

"2400", 

2400L 

>, 

{ 

"3600", 

3600L 

}> 

{ 

"4800" , 

4800L 

}, 

{ 

"7200" , 

7200L 

}, 

{ 

"9600" , 

9600L 

}, 

{ 

"19200", 

19200L 

> 


}; 


/* . Main Application Function . */ 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCF_TITLEBAR j FCF_SYSMENU j FCF_ICON ] 

FCF_SIZEBORDER | FCF_MINMAX | FCF_TASKLIST | 
FCF_SHELLPOSITION j FCF_NOBYTEALIGN; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 
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WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

/* Create the main application window */ 
hWndFrame = WinCreateStdWindow (HWNDJDESKTOP, 0, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

/* Create child windows */ 

InitializeAppWindow (hWndClient); 

/* Show the main window in a maximized state */ 

WinSetWindowPos (hWndFrame, 0, 0L, 0L, 0L, 0L, 

SWP_MAXIMIZE | SWP_SH0W); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 

} 

/* .. CommStatus Thread Function .. */ 

/* 

The CommStatus thread is responsible for querying the current 
communications line and status flags and determining if any 
of the flags have changed. For each set of flags or values that 
has changed, a message is posted to the main message queue thread 
so that it can update the LED controls. 

Access to the communication port file handle (hFile) is protected 
within a critical section. 

This is a Non-Message queue thread so it cannot send messages to 
a message queue thread. 

*/ 

VOID CommStatusThread (ULONG ulThreadParam) 

{ 

RXQUEUE NewReceiveQueue, 

NewTransmitQueue; 

BYTE NewComStatus, 

NewT ransmitStatus, 

NewModemlnput; 

USHORT NewComEvent, 

NewComError; 

MODEMSTATUS NewModemOutput; 
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do 

{ 

/* Query all of the line and status flags */ 

DosEnterCritSec (); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMEVENT, 

NULL, 0L, 0L, &NewComEvent, 2L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMSTATUS, 

NULL, 0L, 0L, &NewComStatus, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETINQUECOUNT, 

NULL, 0L, 0L, &NewReceiveQueue, sizeof(RXQUEUE), 0L); 
DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETOUTQUECOUNT, 

NULL, 0L, 0L, &NewTransmitQueue, sizeof(RXQUEUE), 0L); 
DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMINPUT, 

NULL, 0L, 0L, &NewModemInput, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMOUTPUT, 

NULL, 0L, 0L, &NewModemOutput, sizeof(MODEMSTATUS), 0L); 
DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETLINESTATUS, 

NULL, 0L, 0L, &NewTransmitStatus, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMERROR, 

NULL, 0L, 0L, &NewComError, 2L, 0L); 

DosExitCritSec (); 

/* Determine if any values have changed -- if so then 
post message */ 

if (NewReceiveQueue.cch != ReceiveQueue.cch) 

{ 

ReceiveQueue = NewReceiveQueue; 

WinPostMsg (hWndStatus, WM_USER_RECEIVEQUEUE, 0L, 0L); 

} 

if (NewTransmitQueue.cch != TransmitQueue.cch) 

{ 

TransmitQueue = NewTransmitQueue; 

WinPostMsg (hWndStatus, WM_USER_TRANSMITQUEUE, 0L, 0L); 

} 

if (NewComStatus != ComStatus) 

{ 

ComStatus = NewComStatus; 

WinPostMsg (hWndStatus, WM_USER_COMSTATUS, 0L, 0L); 

} 

if (NewTransmitStatus != TransmitStatus) 

{ 

TransmitStatus = NewTransmitStatus; 

WinPostMsg (hWndStatus, WM_USER_TRANSMITSTATUS, 0L, 0L); 

} 

if (NewComEvent != ComEvent) 

{ 
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ComEvent = NewComEvent; 

WinPostMsg (hWndStatus, WM_USER_COMEVENT, 0L, 0L); 

} 

if (NewComError != ComError) 

{ 

ComError = NewComError; 

WinPostMsg (hWndStatus, WM_USER_COMERROR, 0L, 0L); 

} 

if (NewModemlnput != Modemlnput) 

{ 

Modemlnput = NewModemlnput; 

WinPostMsg (hWndStatus, WM_USER_MODEMINPUT, 0L, 0L); 

} 

if (NewModemOutput.fbModemOn != ModemOutput.fbModemOn) 

{ 

ModemOutput = NewModemOutput; 

WinPostMsg (hWndStatus, WM_USER_MODEMOUTPUT, 0L, 0L); 

} 

/* Go to sleep for 0.2 seconds */ 

DosSleep(200); 

} 

while (TRUE); 

} 

/* . ReceiveData Thread Function . */ 


The ReceiveData thread is responsible for reading the data from 
the communications port and placing the bytes into the Receive 
Buffer. When a carriage return character (0x0D) is received, a 
message is posted to the main message queue thread so that it 
can insert the line into the Remote listbox. If all data has 
been processed from the communications port and it has not 
received the carriage return character, then a message is posted 
to the main message queue thread so that it can update the 
Remote text window. 

Access to the communication port file handle (hFile) is protected 
within a critical section. In order to protect the receive queue 
buffer from being updated before the main message queue thread 
can process the posted message, an event semaphore is used. The 
event semaphore is reset prior to posting the message and this 
thread will wait for the main message queue thread to post the 
event semaphore before continuing. 

This is a Non-Message queue thread, so it cannot send messages to 
a message queue thread. 
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VOID ReceiveDataThread (ULONG ulThreadParam) 


CHAR 

szBuffer[255]; 

ULONG 

ulBytesRead; 

ULONG 

ulEventCnt; 

ULONG 

ulPos; 

BOOL 

blnsert; 

do 



{ 

/* Read data from the communications port */ 

ulBytesRead = 0L; 

DosEnterCritSec (); 

DosRead (hFile, szBuffer, (ULONG)sizeof(szBuffer), &ulBytesRead); 

DosExitCritSec (); 

if (ulBytesRead) 

{ 

ulPos = 0; 
blnsert = FALSE; 

while (ulPos < ulBytesRead) 

{ 

switch (szBuffer[ulPos]) 

{ 

case 0x0A: /* Line feed */ 

ulPos++; 
break; 

case 0x0D: /* Carriage return */ 

szReceiveBuffer[usNextPos] = '\0 1 ; 
usNextPos = 0; 
blnsert = TRUE; 
ulPos++; 
break; 

case 0x08: /* Backspace */ 

if (usNextPos) 
usNextPos- -; 
ulPos++; 
break; 

default: 

if (usNextPos == 254) 

{ 

szReceiveBufferfusNextPos] = 1 \0'; 
usNextPos = 0; 
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blnsert = TRUE; 

} 

else 

szReceiveBuffer[usNextPos++] = szBuffer[ulPos++]; 
break; 

} 

if (blnsert) 

{ 

/* Clear the event semaphore */ 

DosResetEventSem (hevRcvQueue, &ulEventCnt); 

WinPostMsg (hWndClient, WM_USER_RCVLIST, 0L, 0L); 

/* Wait for main message queue thread to process message */ 
DosWaitEventSem (hevRcvQueue, 1000); 

blnsert = FALSE; 

} 

} 

/* Clear the event semaphore */ 

DosResetEventSem (hevRcvQueue, &ulEventCnt); 

szReceiveBuffer[usNextPos] = 1 \0 1 ; 

WinPostMsg (hWndClient, WM_USER_RCVTEXT, 0L, 0L); 

/* Wait for main message queue thread to process message */ 
DosWaitEventSem (hevRcvQueue, 1000); 

} 

/* Go to sleep for 0.1 seconds */ 

DosSleep (100); 

} 

while (TRUE); 

} 


/* . Local Functions . */ 

VOID ConnectToPort (HWND hWnd) 

{ 

ULONG ulAction; 

szCom[3] = (CHAR)( 1 1 1 + ulPort); 
if (IDosOpen (szCom, &hFile, &ulAction, 0L, 

FILE_NORMAL, FILE_0PEN, 

OPEN_ACCESS_READWRITE j OPEN_SHARE_DENYNONE, 0L)) 
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if (!(bConnected = SetPortSettings (hWnd))) 

DosClose (hFile); 

/* Create the event semaphore for the receive queue */ 
DosCreateEventSem ("Wsem32\\RCVQUEUE M , &hevRcvQueue, 0, TRUE); 

/* Start the CommStatus and ReceiveData threads */ 
DosCreateThread (&StatusThreadID 3 (PFNTHREAD)CommStatusThread, 
0L, 0, 0x10000); 

DosCreateThread (&ReadThreadID, (PFNTHREAD)ReceiveDataThread, 

0L 3 0 3 0x10000); 

/* Set the priority of the CommStatus thread to idle time */ 
DosSetPriority (PRTYS_THREAD 3 PRTYC_IDLETIME, 0 3 StatusThreadID) 


if (bConnected) 

{ 

WinEnableControl (hWnd 3 IDC_CONNECT, FALSE); 
WinEnableControl (hWnd, IDC_HANGUP 3 TRUE); 
WinEnableWindow (hWndLocalEdit, TRUE); 
WinSetFocus (HWND_DESKTOP, hWndLocalEdit); 

} 

else 

WinMessageBox (HWND_DESKTOP, hWnd, 

"Unable to connect", "Phone Application", 
0, MB_ERROR | MB_0K); 


return; 

} 

VOID DelnitializeControls (HWND hWnd) 

{ 

CHAR szTxt[2]; 

ULONG ulValue; 

/* Query values */ 

Portlnfo[ulPort].Baudlndex = 

(ULONG)WinSendDlgItemMsg (hWnd, IDC_BAUDRATE, 
SLM_QUERYSLIDERINFO, 

MPFR0M2SH0RT (SMA_SLIDERARMPOSITION, SMA_INCREMENTVALUE), 
0L); 

PortInfo[ulPort].BaudRate = 

BaudRates[PortInfo[ulPort].Baudlndex].ulValue; 
if (WinQueryButtonCheckstate (hWnd, IDC_DATABITS_5)) 

Portlnfo[ulPort].LineControl.bDataBits = 5; 
else if (WinQueryButtonCheckstate (hWnd, IDC_DATABITS_6)) 
PortlnfofulPort].LineControl.bDataBits =6; 
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else if (WinQueryButtonCheckstate (hWnd, IDC_DATABITS_7)) 
PortInfo[ulPort].LineControl.bDataBits = 7; 
else if (WinQueryButtonCheckstate (hWnd, IDC_DATABITS_8)) 

Portlnfo[ulPort].LineControl.bDataBits = 8; 
if (WinQueryButtonCheckstate (hWnd, IDC_ST0PBITS_1)) 
PortInfo[ulPort].LineControl.bStopBits = 0; 
else if (WinQueryButtonCheckstate (hWnd, IDC_ST0PBITS_15)) 
PortInfo[ulPort].LineControl.bStopBits = 1; 
else if (WinQueryButtonCheckstate (hWnd, IDC_ST0PBITS_2)) 
PortInfo[ulPort].LineControl.bStopBits = 2; 

if (WinQueryButtonCheckstate (hWnd, IDC_PARITY_NONE)) 
PortInfo[ulPort].LineControl.bParity = 0; 
else if (WinQueryButtonCheckstate (hWnd, IDC__PARITY_ODD)) 

Portlnfo[ulPort].LineControl.bParity = 1; 
else if (WinQueryButtonCheckstate (hWnd, IDC_PARITY_EVEN)) 
Portlnfo[ulPort].LineControl.bParity = 2; 
else if (WinQueryButtonCheckstate (hWnd, IDC_PARITY_MARK)) 
PortInfo[ulPort].LineControl.bParity = 3; 
else if (WinQueryButtonCheckstate (hWnd, IDC_PARITY_SPACE)) 
PortInfo[ulPort].LineControl.bParity = 4; 

PortInfo[ulPort].DCBInfo.fbCtlHndShake = 0; 

Portlnfo[ulPort].DCBInfo.fbFlowReplace = 0; 
if (WinQueryButtonCheckstate (hWnd, IDC_HANDSHAKING_DTRC)) 
PortInfo[ulPort].DCBInfo.fbCtlHndShake |= MODE_DTR_CONTROL; 
if (WinQueryButtonCheckstate (hWnd, IDC_HANDSHAKING__DTRI)) 

Portlnfo[ulPort].DCBInfo.fbCtlHndShake ]= MODE_DTR_HANDSHAKE; 
if (WinQueryButtonCheckstate (hWnd, IDC__HANDSHAKING_CTSO)) 

Portlnfo[ulPort].DCBInfo.fbCtlHndShake \= MODE_CTS_HANDSHAKE; 
if (WinQueryButtonCheckstate (hWnd, IDC__HANDSHAKING_DSRO)) 

PortInfo[ulPort].DCBInfo.fbCtlHndShake |= M0DE_DSRJHANDSHAKE; 
if (WinQueryButtonCheckstate (hWnd, IDC_HANDSHAKING_DCDO)) 

PortInfo[ulPort].DCBInfo.fbCtlHndShake |= MODE_DCD__HANDSHAKE; 
if (WinQueryButtonCheckstate (hWnd 3 IDC_HANDSHAKING_DSRI)) 

PortInfo[ulPort].DCBInfo.fbCtlHndShake ]= MODE_DSR_SENSITIVITY 

if (WinQueryButtonCheckstate (hWnd, IDC_HANDSHAKING_RTSI)) 

PortInfo[ulPort].DCBInfo.fbFlowReplace |= MODE_RTS_HANDSHAKE; 
if (WinQueryButtonCheckstate (hWnd, IDC_FL0WC0NTR0L_X0NX0FFT)) 
Portlnfo[ulPort].DCBInfo.fbFlowReplace |= MODE_AUTO_TRANSMIT; 
if (WinQueryButtonCheckstate (hWnd, IDC_FLOWCONTROL_XONXOFFR)) 
PortInfo[ulPort].DCBInfo.fbFlowReplace |= MODE_AUTO_RECEIVE; 
if (WinQueryButtonCheckstate (hWnd, IDC_FLOWCONTROL_ERRORREP)) 
PortInfo[ulPort].DCBInfo.fbFlowReplace |= MODE_ERROR_CHAR; 
if (WinQueryButtonCheckstate (hWnd, IDC_FLOWCONTROL_NULLSTRIP)) 
PortInfo[ulPort].DCBInfo.fbFlowReplace |= MODE_NULL_STRIPPING; 
if (WinQueryButtonCheckstate (hWnd, IDC_FLOWCONTROL_BREAKREP)) 
PortInfo[ulPort].DCBInfo.fbFlowReplace |= MODE_BREAK_CHAR; 
if (WinQueryButtonCheckstate (hWnd, IDC_FL0WC0NTR0L_RTSC)) 
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PortInfo[ulPort].DCBInfo.fbFlowReplace J> MODE_RTS_CONTROL; 
if (WinQueryButtonCheckstate (hWnd, IDC_FLOWCONTROL_TOGGLING)) 
PortlnfofulPort].DCBInfo.fbFlowReplace |= MODE_TRANSMIT_TOGGLE; 
WinQueryDlgltemText (hWnd, IDC_XONCHAR, 2, szTxt); 

PortInfo[ulPort].DCBInfo.bXONChar = szTxt[0]; 

WinQueryDlgltemText (hWnd, IDC_XOFFCHAR, 2, szTxt); 
PortlnfofulPort].DCBInfo.bXOFFChar = szTxt[0]; 

WinQueryDlgltemText (hWnd, IDC_ERRORREPCHAR, 2, szTxt); 
PortlnfofulPort].DCBInfo.bErrorReplacementChar = szTxt[0]; 
WinQueryDlgltemText (hWnd, IDC_BREAKREPCHAR , 2 3 szTxt); 

PortlnfofulPort].DCBInfo.bBreakReplacementChar = szTxt[0]; 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_WRITE 3 SPBM_QUERYVALUE, 
(MPARAM)&ulValue, (MPARAM)0L); 

PortlnfofulPort].DCBInfo.usWriteTimeout = (USHORT)ulValue; 
WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_READ 3 SPBM_QUERYVALUE, 
(MPARAM)&ulValue, (MPARAM)0L); 

PortlnfofulPort].DCBInfo.usReadTimeout = (USHORT)ulValue; 

PortlnfofulPort].DCBInfo.fbTimeout = 

(BYTE)(PortlnfofulPort].DCBInfo.fbTimeout & 0X0F8); 
if (PortlnfofulPort].DCBInfo.usWriteTimeout == 0) 

PortlnfofulPort].DCBInfo.fbTimeout | = MODE_NO_WRITE_TIMEOUT; 
if (PortlnfofulPort].DCBInfo.usReadTimeout == 0 ) 

PortlnfofulPort].DCBInfo.fbTimeout |= MODE_NOWAIT_READ_TIMEOUT; 
else 

PortlnfofulPort].DCBInfo.fbTimeout |= MODE_READ_TIMEOUT; 
return; 


VOID HangUpFromPort (HWND hWnd) 

{ 

BYTE Cmd; 

/* Flush the input and output buffers */ 

DosDevIOCtl (hFile, IOCTL_GENERAL, DEV_FLUSHOUTPUT, (PV0ID)&Cmd 3 1L, 
NULL, NULL, 0L, NULL) ; 

DosDevIOCtl (hFile, IOCTL_GENERAL, DEV_FLUSHINPUT, (PVOID)&Cmd, 1L, 
NULL, NULL, 0L, NULL); 

if (IDosClose (hFile)) 

{ 

WinEnableControl (hWnd, IDC_CONNECT, TRUE); 

WinEnableControl (hWnd, IDC_HANGUP, FALSE); 

WinEnableWindow (hWndLocalEdit, FALSE); 

/* Stop the CommStatus and ReceiveData threads */ 

DosKillThread (StatusThreadID); 

DosKillThread (ReadThreadID); 
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/* Close the receive data event semaphore */ 

DosCloseEventSem (hevRcvQueue); 

bConnected = FALSE; 

} 

else 

WinMessageBox (HWND_DESKTOP, hWnd, 

"Unable to hangup", "Phone Application", 

0, MB_ERR0R j MB_0K); 

return; 

} 

VOID InitializeAppWindow (HWND hWnd) 

{ 

LONG IColor; 

RegisterLEDClass (hab); 

/* Local Connections Windows */ 

hWndLocalTitle = WinCreateWindow (hWnd, WC_STATIC, 

"Local Connection", 

WS_VISIBLE | SS_TEXT \ DT_B0TT0M, 

0L, 0L, 140L, 16L, hWnd, HWND_BOTTOM, 1, NULL, NULL); 

hWndLocalEdit = WinCreateWindow (hWnd, WC_ENTRYFIELD, "", 
WS_VISIBLE | ES_AUTOSCROLL j WS_GR0UP | WS_TABSTOP | 
WS_DISABLED, 

0L, 0L, 0L, 0L, hWnd, HWND_B0TT0M, 2, NULL, NULL); 

hWndLocalBevell = WinCreateWindow (hWnd, BEVELCLASS, "", 

WS_VISIBLE | BVS_PREVWINDOW, 

0L, 0L, 0L, 0L, hWnd, HWND_B0TT0M, 0, NULL, NULL); 

WinSendMsg (hWndLocalBevell, BVM_SETTHICKNESS, MPFROMSHORT(2), 0L); 

hWndLocalList = WinCreateWindow (hWnd, WC_LISTBOX, "", 

WS_VISIBLE | LS_N0ADJUSTPOS J LS_HORZSCROLL | WS_TABSTOP, 

0L, 0L, 0L, 0L, hWnd, HWND_B0TT0M, 3, NULL, NULL); 

hWndLocalBevel2 = WinCreateWindow (hWnd, BEVELCLASS, "", 

WS_VISIBLE | BVS_PREVWINDOW, 

0L, 0L, 0L, 0L, hWnd, HWND_B0TT0M, 0, NULL, NULL); 

WinSendMsg (hWndLocalBevel2, BVM_SETTHICKNESS, MPFROMSHORT(2), 0L); 


/* Remote Connections Windows */ 

hWndRemoteTitle = WinCreateWindow (hWnd, WC_STATIC, 
"Remote Connection", 
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WS_VISIBLE | SS_TEXT | DT_B0TT0M, 

0L, 0L, 140L 3 16L, hWnd 3 HWND_BOTTOM 3 4, NULL, NULL); 

hWndRemoteText = WinCreateWindow (hWnd, WC_STATIC 3 " 11 3 
WS_VISIBLE | SS_TEXT J DT_LEFT j DT_VCENTER, 

0L 3 0L 3 0L 3 0L, hWnd, HWND_BOTTOM, 5, NULL, NULL); 

hWndRemoteBevell = WinCreateWindow (hWnd, BEVELCLASS, " 11 , 

WS_VISIBLE | BVS_PREVWINDOW, 

0L, 0L, 0L, 0L, hWnd, HWND_BOTTOM, 0, NULL, NULL); 

WinSendMsg (hWndRemoteBevell, BVM_SETTHICKNESS, MPFROMSHORT(2), 0L); 

hWndRemoteList = WinCreateWindow (hWnd, WC_LISTBOX, "", 

WS_VISIBLE | LS_NOADJUSTPOS | LS_HORZSCROLL, 

0L, 0L, 0L, 0L, hWnd, HWND__BOTTOM, 6, NULL, NULL); 

hWndRemoteBevel2 = WinCreateWindow (hWnd, BEVELCLASS, 1,11 , 

WS_VISIBLE | BVS_PREVWINDOW, 

0L, 0L, 0L, 0L, hWnd, HWND_BOTTOM, 0, NULL, NULL); 

WinSendMsg (hWndRemoteBevel2, BVM_SETTHICKNESS, MPFROMSHORT(2), 0L); 


/* Load the dialog windows */ 

hWndButtons = WinLoadDlg (hWnd, hWnd, StatusDlgProc, 0L, 
IDD_BUTTONS, NULL); 

hWndStatus = WinLoadDlg (hWnd, hWnd, StatusDlgProc, 0L, 
IDD_STATUS, NULL); 


/* Initialize settings of certain control windows */ 

WinSendMsg (hWndLocalEdit, EM_SETTEXTLIMIT, MPFR0MSH0RT(254), 0L); 
IColor = CLR_DARKCYAN; 

WinSetPresParam (hWndLocalList, PP_BACKGROUNDCOLORINDEX, 
sizeof(IColor), &lColor); 

IColor = CLR_DARKRED; 

WinSetPresParam (hWndRemoteList, PP_BACKGROUNDCOLORINDEX, 
sizeof(IColor), &lColor); 

return; 

} 

VOID InitializeControls (HWND hWnd, BOOL binit) 

{ 

ULONG ullnx; 

CHAR szTxt[2] = " "; 
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/* Set limits and attributes */ 
if (binit) 

{ 

for (ullnx = 0; ullnx < 13; ullnx++) 

{ 

WinSendDlgltemMsg (hWnd, IDCJ3AUDRATE, SLM_SETTICKSIZE, 
MPFR0M2SH0RT (SMA_SETALLTICKS, 5), 0L); 

WinSendDlgltemMsg (hWnd, IDC_BAUDRATE, SLM_SETSCALETEXT, 
MPFROMSHORT(ullnx), MPFROMP(BaudRates[ulInx].szTxt)); 

} 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_WRITE, SPBM_SETTEXTLIMIT, 
(MPARAM)4, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_WRITE, SPBM_SETLIMITS, 
(MPARAM)9999L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_READ, SPBM_SETTEXTLIMIT, 
(MPARAM)4, (MPARAM)0); 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_READ, SPBM_SETLIMITS, 
(MPARAM)9999L, (MPARAM)0L); 

WinSendDlgltemMsg (hWnd, IDC_XONCHAR, EM_SETTEXTLIMIT, 

MPFROMSHORT(1), 0L); 

WinSendDlgltemMsg (hWnd, IDC_XOFFCHAR, EM_SETTEXTLIMIT, 
MPFROMSHORT(1), 0L); 

WinSendDlgltemMsg (hWnd, IDC_ERRORREPCHAR, EM_SETTEXTLIMIT, 
MPFROMSHORT(1), 0L); 

WinSendDlgltemMsg (hWnd, IDC_BREAKREPCHAR, EM_SETTEXTLIMIT, 
MPFROMSHORT(1), 0L); 

for (ullnx = 0; ullnx < ulNumPorts; ullnx++) 

{ 

szCom[3] = (CHAR)('1' + ullnx); 

WinSendDlgltemMsg (hWnd, IDC_PORT, LM_INSERTITEM, 

(MPARAM)LIT_END, szCom); 

} 

WinSendDlgltemMsg (hWnd, IDC_P0RT, LM_SELECTITEM, 

(MPARAM)ulPort, (MPARAM)TRUE); 

} 

/* Set values */ 

WinSendDlgltemMsg (hWnd, IDC_BAUDRATE, SLM_SETSLIDERINFO, 

MPFR0M2SH0RT (SMA_SLIDERARMPOSITION, SMA_INCREMENTVALUE), 
MPFROMSHORT(PortInfo[ulPort].Baudlndex)); 

WinCheckButton (hWnd, 

IDC_DATABITS_5+PortInfo[ulPort].LineControl.bDataBits-5, TRUE); 
WinCheckButton (hWnd, 

IDC_STOPBITS_1+PortInfo[ulPort].LineControl.bStopBits, TRUE); 
WinCheckButton (hWnd, 

IDC_PARITY_NONE+Portlnfo[ulPort].LineControl.bParity, TRUE); 
WinCheckButton (hWnd, IDC_HANDSHAKING_DTRC, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_DTR_CONTROL ? 
TRUE : FALSE); 
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WinCheckButton (hWnd, IDC_HANDSHAKING_DTRI, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_DTR_HANDSHAKE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_HANDSHAKING_CTS0, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_CTS_HANDSHAKE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_HANDSHAKING_DSRO, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_DSR_HANDSHAKE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_HANDSHAKING_DCDO, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_DCD_HANDSHAKE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_HANDSHAKING_DSRI, 

PortInfo[ulPort].DCBInfo.fbCtlHndShake & MODE_DSR_SENSITIVITY ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_HANDSHAKING_RTSI, 

Port Info[ulPort].DCBInfo.fbFlowReplace & MODE_RTS_HANDSHAKE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_XONXOFFT, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_AUTO_TRANSMIT ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_XONXOFFR, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_AUTO_RECEIVE ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_ERRORREP, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_ERROR CHAR ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_NULLSTRIP, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_NULL_STRIPPING ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_BREAKREP, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_BREAK_CHAR ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_RTSC, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & M0DE_RTS_C0NTR0L ? 

TRUE : FALSE); 

WinCheckButton (hWnd, IDC_FLOWCONTROL_TOGGLING, 

PortInfo[ulPort].DCBInfo.fbFlowReplace & MODE_TRANSMIT_TOGGLE ? 

TRUE : FALSE); 

szTxt[0] = PortInfo[ulPort].DCBInfo.bXONChar; 

WinSetDlgltemText (hWnd, IDC_XONCHAR, szTxt); 

szTxt[0] = PortInfo[ulPort].DCBInfo.bXOFFChar; 

WinSetDlgltemText (hWnd, IDC_XOFFCHAR, szTxt); 

szTxt[0] = PortInfo[ulPort].DCBInfo.bErrorReplacementChar; 

WinSetDlgltemText (hWnd, IDC_ERRORREPCHAR, szTxt); 

szTxt[0] = Portlnfo[ulPort].DCBInfo.bBreakReplacementChar; 

WinSetDlgltemText (hWnd, IDC_BREAKREPCHAR, szTxt); 

WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_WRITE, SPBM_SETCURRENTVALUE, 
(MPARAM)PortInfo[ulPort].DCBInfo.usWriteTimeout, (MPARAM)0L); 
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WinSendDlgltemMsg (hWnd, IDC_TIMEOUT_READ, SPBM_SETCURRENTVALUE, 
(MPARAM)PortInfo[ulPort].DCBInfo.usReadTimeout, (MPARAM)0L); 

return; 


VOID PositionWindows (ULONG ulWidth, ULONG ulHeight) 

{ 

PSWP pSwp; 

RECTL Recti; 

/* Allocate memory to hold the SWP structures */ 
if (IDosAllocMem ((PPVOID)&pSwp, sizeof(SWP) * 8L, fALLOC)) 
{ 

/* Position buttons window */ 

WinQueryWindowRect (hWndButtons, &Rectl); 
pSwp [ 0 ] . f 1 = SWPJ/IOVE; 

pSwp[0].x = ulWidth - Recti.xRight - 5; 
pSwp[0].y = ulHeight - Recti.yTop - 20; 
pSwp[0].hwnd = hWndButtons; 

/* Position status window */ 

WinQueryWindowRect (hWndStatus, &Rectl); 

pSwp[ 1 ] .fl = SWPJ/IOVE; 

pSwp[1].x = 0; 

pSwp[1].y = 0; 

pSwp[1].hwnd = hWndStatus; 

ulWidth = pSwp[0].x - 5; 

ulHeight = (ulHeight - Recti.yTop) » 1; 

/* Position the local title window */ 
pSwp[2] .f 1 = SWPJ/IOVE; 

pSwp[2].x =5; 

pSwp[2].y = Recti.yTop + (ulHeight « 1) - 16; 
pSwp[2].hwnd = hWndLocalTitle; 

/* Size and position local edit window */ 

pSwp[3] .f 1 = SWPJ/IOVE | SWP_SIZE; 

pSwp[3].x =8; 

pSwp[3].y = pSwp[2].y - 20; 

pSwp[3].cx = ulWidth - 16; 

pSwp[3].cy =16; 

pSwp[3].hwnd = hWndLocalEdit; 

/* Size and position local list window */ 
pSwp[4] .f 1 = SWPJ/IOVE i SWP_SIZE; 

pSwp[4].x =8; 

pSwp[4].y = Recti.yTop + ulHeight + 8; 
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pSwp[4].cx = ulWidth - 16; 
pSwp[4].cy = ulHeight - 50; 
pSwp[4].hwnd = hWndLocalList; 

/* Position the remote title window */ 
pSwp[5].f1 = SWP_MOVE; 

pSwp[5].x =5; 

pSwp[5].y = Recti.yTop + ulHeight - 16; 
pSwp[5].hwnd = hWndRemoteTitle; 

/* Size and position remote text window */ 

pSwp[6].f1 = SWP_MOVE | SWP_SIZE; 

pSwp[6].x = 8; 

pSwp[6].y = pSwp[5].y - 20; 

pSwp[6].cx = ulWidth - 16; 

pSwp[6].cy =16; 

pSwp[6].hwnd = hWndRemoteText; 

/* Size and position remote list window */ 

pSwp[7].f1 = SWP_MOVE | SWP_SIZE; 

pSwp[7].x =8; 

pSwp[7].y = Recti.yTop + 8; 

pSwp[7].cx = ulWidth - 16; 

pSwp[7].cy = ulHeight - 50; 

pSwp[7].hwnd = hWndRemoteList; 

/* Arrange the windows */ 

WinSetMultWindowPos (hab, pSwp, 8L); 

/* Tell the bevel windows to resize themselves since the window 
they were sized around has changed its size */ 

WinSendMsg (hWndLocalBevell, BVM_RESIZE, MPFR0M2SH0RT(2 J 2), 0L); 
WinSendMsg (hWndLocalBevel2, BVM_RESIZE, MPFR0M2SH0RT(2,2), 0L); 
WinSendMsg (hWndRemoteBevell, BVM_RESIZE, MPFR0M2SH0RT(2,2), 0L); 
WinSendMsg (hWndRemoteBevel2 3 BVM_RESIZE 3 MPFROM2SHORT(2 3 2) 3 0L); 

/* Free the allocated memory */ 

DosFreeMem ((PVOID)pSwp); 


return; 

} 

VOID QueryBaudRate (ULONG ulPort) 

{ 

DosDevIOCtl (hFile 3 IOCTL_ASYNC 3 ASYNC_GETBAUDRATE 3 

NULL, 0L , 0L 3 (PVOID)&PortInfo[ulPort].BaudRate, 2L, 0L); 
PortInfo[ulPort].Baudlndex = 12; 
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while ((Portlnfo[ulPort].Baudlndex > 0) && 

(PortlnfofulPort].BaudRate < 

BaudRates[PortInfo[ulPort].Baudlndex].ulValue)) 
PortInfo[ulPort].Baudlndex - - ; 

return; 

} 

VOID QueryDCBInfo (ULONG ulPort) 

{ 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETDCBINFO, 

NULL, 0L, 0L, (PVOID)&PortInfo[ulPort].DCBInfo, 
sizeof(DCBINFO), 0L); 

return; 

} 

VOID QueryLineCtrl (ULONG ulPort) 

{ 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETLINECTRL, 

NULL, 0L, 0L, (PVOID)&PortInfo[ulPort].LineControl, 
sizeof(LINECONTROL), 0L); 

return; 

} 

VOID QueryValidCommPorts () 

{ 

ULONG ullnx; 

ULONG ulAction; 

BYTE cCommPorts; 

/* Determine the number of communication ports on the system */ 
DosDevConfig (&cCommPorts, DEVINF0_RS232); 
ulNumPorts = (ULONG)cCommPorts; 

/* Attempt to query current com port settings */ 
for (ullnx = 0; ullnx < ulNumPorts; ullnx++) 

{ 

szCom[3] = (CHAR)('1' + ullnx); 

if (IDosOpen (szCom, &hFile, &ulAction, 0L, FILE_NORMAL, 

FILE_OPEN, OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L)) 

{ 

QueryBaudRate (ullnx); 

QueryDCBInfo (ullnx); 

QueryLineCtrl (ullnx); 

DosClose (hFile); 
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PortInfo[ulInx].DCBInfo.usWriteTimeout = 0 ; 

PortInfo[ulInx].DCBInfo.usReadTimeout = 0 ; 

} 

else 

{ 

/* Set to default values */ 


PortInfo[ulInx].Baudlndex = ii; 

Portlnfofullnx].BaudRate = 9600; 

Portlnfo[ullnx].LineControl.bDataBits = 5; 

Portlnfofullnx].LineControl.bStopBits = 0 ; 

Portlnfofullnx].LineControl.bParity = 0 ; 

Portlnfofullnx].DCBInfo.fbCtlHndShake = 0 ; 

Portlnfofullnx].DCBInfo.fbFlowReplace = 0 ; 

Portlnfofullnx].DCBInfo.bXONChar = 0 x 11 ; 

Portlnfofullnx].DCBInfo.bXOFFChar = 0x13; 

Portlnfo[ullnx].DCBInfo.bErrorReplacementChar = ' '; 

Portlnfofullnx].DCBInfo.bBreakReplacementChar = ' 1 ; 

Portlnfofullnx].DCBInfo.usWriteTimeout = 0 ; 

Portlnfofullnx].DCBInfo.usReadTimeout = 0 ; 

} 

} 


return; 

} 

BOOL SetPortSettings (HWND hWnd) 

{ 

BOOL bSet = 

!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETBAUDRATE, 

&PortInfo[ulPort].BaudRate, 2L, NULL, NULL, 0L, NULL) && 

!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETLINECTRL, 

&PortInfo[ulPort].LineControl, 3L, NULL, NULL, 0L, NULL) && 
!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETDCBINFO, 

&PortInfo[ulPort].DCBInfo, sizeof(DCBINFO), 0L, NULL, 0L, 
NULL); 

if (!bSet) 

WinMessageBox (HWND_DESKTOP, hWnd, 

"Unable to set port settings", "Phone Application", 

0, MB_ERROR | MB_0K); 

return (bSet); 

} 

VOID ToggleTransmit (HWND hWnd) 

{ 

/* Toggle the data transmission state */ 


if (bTransmitting) 

{ 
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if (IDosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_STOPTRANSMIT, 
NULL, 0L, NULL, NULL, 0L, NULL)) 

{ 

bTransmitting = FALSE; 

WinSetDlgltemText (hWnd, IDC_TRANSMIT, "Start"); 

} 

} 

else 

{ . . 

if (IDosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_STARTTRANSMIT, 

NULL, 0L, NULL, NULL, 0L, NULL)) 

{ 

bTransmitting = TRUE; 

WinSetDlgltemText (hWnd, IDC_TRANSMIT, "Stop"); 

} 

} 

return; 

} 

VOID TransmitLine () 

{ 

CHAR szBuffer[255]; 

ULONG ulLen; 

ULONG ulBytesWritten; 

WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_WRT, WM_ENABLE, 
MPFROMSHORT(TRUE), 0L); 

/* If data transmission is turned off then beep -- can't send 
the data */ 
if (!bTransmitting) 

{ 

DosBeep (500, 50); 
return; 


/* Limit the number of lines in the listbox */ 
if (ulNumLocalLines == 100) 

WinSendMsg (hWndLocalList, LM_DELETEITEM, (MPARAM)99L, 0L); 
ulNumLocalLines - -; 

ulLen = WinQueryWindowText (hWndLocalEdit, sizeof(szBuffer)-2, 
szBuffer); 

szBuffer[ulLen++] = 0x0D; 
szBuffer[ulLen++] = 0x0A; 
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/* Write data to the communications port */ 

DosEnterCritSec (); 

if (IDosWrite (hFile, szBuffer, ulLen, &ulBytesWritten)) 

{ 

szBuffer[ulLen-2] = '\0'; 

WinSendMsg (hWndLocalList, LM_INSERTITEM, 0L, (MPARAM)szBuffer); 

WinSetWindowText (hWndLocalEdit, ""); 

ulNumLocalLines++; 


DosExitCritSec (); 

WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_WRT J WM_EMABLE, 
MPFROMSHORT(FALSE), 0L); 

return; 


/* .Window and Dialog Functions .— */ 

MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

RECTL Recti; 

HPS hps; 

switch (msg) 

{ 

case WM_CREATE: 

{ 

LONG RGBBack = 0X00CCCCCCL; 

LONG RGBText = 0X00000000L; 

WinSetPresParam (hWnd, PP_FONTNAMESIZE, FONTNAMELEN, HELV8FONT); 
WinSetPresParam (hWnd, PP_BACKGROUNDCOLOR, 
sizeof(RGBBack), &RGBBack); 

WinSetPresParam (hWnd, PP_FOREGROUNDCOLOR 3 
sizeof(RGBText) 3 &RGBText); 

QueryValidCommPorts (); 

} 

break; 

case WM_USER_RCVLIST: 

/* Data in the receive buffer is a complete line -- insert it 
into the Remote listbox. */ 
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WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_RED, WM_ENABLE, 
MPFROMSHORT(TRUE), 0L); 

/* Limit the number of lines in the listbox */ 
if (ulNumRemoteLines == 100) 

{ 

WinSendMsg (hWndRemoteList, LM_DELETEITEM, (MPARAM)99L, 0L); 
ulNumRemoteLines--; 

} 

WinSendMsg (hWndRemoteList, LM_INSERTITEM, 0L, 

(MPARAM)szReceiveBuffer); 
ulNumRemoteLines++; 

/* Post the receive data event semaphore to notify the 

ReceiveData thread that we are done with szReceiveBuffer */ 
DosPostEventSem (hevRcvQueue); 

WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_RED, WM_ENABLE, 
MPFROMSHORT(FALSE), 0L); 
break; 

case WM_USER_RCVTEXT: 

/* Data in the receive buffer is an incomplete line -- update 
the Remote text window */ 

WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_RED, WM_ENABLE, 
MPFROMSHORT(TRUE), 0L); 

WinSetWindowText (hWndRemoteText, szReceiveBuffer); 

/* Post the receive data event semaphore to notify the 

ReceiveData thread that we are done with szReceiveBuffer */ 
DosPostEventSem (hevRcvQueue); 

WinSendDlgltemMsg (hWndStatus, IDC_LINESTATUS_RED, WM_ENABLE, 
MPFROMSHORT(FALSE), 0L); 
break; 

case WM_PAINT: 

hps = WinBeginPaint (hWnd,0,0); 

WinQueryWindowRect (hWnd, &Rectl); 

WinFillRect (hps, &Rectl, CLR_PALEGRAY); 

WinEndPaint (hps); 
break; 

case WM_C0NTR0L: 

/* if we get a doubleclick or enter from the Local listbox 
then copy the text from the listbox to the Local 
edit window */ 
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if ( bConnected && 

(SH0RT2FR0MMP(mpl) == LN_ENTER) && 

((HWND)mp2 == hWndLocalList) ) 

{ 

SHORT slndex; 

CHAR szTxt[255]; 

slndex = (SHORT)WinSendMsg (hWndLocalList, LM_QUERYSELECTION, 
(MPARAM)LIT_FIRST, 0L); 
if (slndex != LIT_NONE) 

{ 

WinSendMsg (hWndLocalList, LM_QUERYITEMTEXT, 

MPFR0M2SH0RT(slndex,255), szTxt); 

WinSetWindowText (hWndLocalEdit, szTxt); 

WinSetFocus (HWND_DESKTOP, hWndLocalEdit); 

} 

} 

break; 

case WM_CHAR: 

/* If the enter key is pressed in either the Local edit or 
Local listbox then transmit the data */ 

if ( bConnected && 

(WinGueryFocus (HWND_DESKTOP) == hWndLocalEdit) && 

!(SHORT1FROMMP(mpl) & KC_KEYUP) && 

(SHORT1FROMMP(mpl) & KC_VIRTUALKEY) && 

( (SH0RT2FR0MMP(mp2) == VK_ENTER) ]| 

(SH0RT2FR0MMP(mp2) == VK_NEWLINE) ) ) 

TransmitLine (); 
break; 

case WM_SIZE: 

PositionWindows ((ULONG)SHORTIFR0MMP(mp2), 

(ULONG)SH0RT2FR0MMP(mp2)); 

break; 
default: 

bHandled = FALSE; 
break; 

} 

if (IbHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mp1,mp2); 
return (mReturn); 

} 
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MRESULT EXPENTRY StatusDlgProc (HWND hWnd, ULONG msg 3 MPARAM mpl 3 

MPARAM mp2) 

{ 

MRESULT mReturn m 0L; 

BOOL bHandled = TRUE; 

switch (msg) 

{ 

case WM_INITDLG: 

CenterWindow (hWnd); 

break; 

case WM_USER_RECEIVEQUEUE: 

WinSetDlgltemShort (hWnd, IDC_QUEUE_IN, ReceiveQueue.cch , 
FALSE); 

break; 

case WM_USER_TRANSMITQUEUE: 

WinSetDlgltemShort (hWnd, IDC_QUEUE_IN, TransmitQueue.cch, 
FALSE); 

break; 

case WM_USER_COMSTATUS: 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_CTS, WM_ENABLE, 
MPFROMSHORT(ComStatus & TX_WAITING_FOR_CTS), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_DST 3 WM_ENABLE , 
MPFROMSHORT(ComStatus & TX_WAITING_FOR_DSR) 3 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_DCD 3 WM_ENABLE, 
MPFROMSHORT(ComStatus & TX_WAITING_FOR_DCD), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_XON, WM_ENABLE, 
MPFROMSHORT(ComStatus & TX_WAITING_FOR_XON), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_XOF, WM_ENABLE, 
MPFROMSHORT(ComStatus & TX_WAITING_TO_SEND_XON), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_BRK, WM_ENABLE, 

MPFROMSHORT(ComStatus & TX_WAITING_WHILE_BREAK_ON ), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_IMM, WM_ENABLE, 
MPFROMSHORT(ComStatus & TX_WAITING_TO_SEND_IMM), 0L); 

WinSendDlgltemMsg (hWnd, IDC_COMMSTATUS_DSR, WM_ENABLE 3 
MPFROMSHORT(ComStatus & TX_WAITING_FOR_DSR), 0L); 

break; 

case WM_USER_TRANSMITSTATUS: 

WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_WRQ 3 WM_ENABLE, 

MPFROMSHORT(TransmitStatus & WRITE_REQUEST_QUEUED ), 0L); 

WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_DTQ 3 WM_ENABLE, 
MPFROMSHORT(TransmitStatus & DATA_IN_TX_QUE ), 0L); 

WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_HTX, WM_ENABLE 3 

MPFROMSHORT(TransmitStatus & HARDWARE_TRANSMITTING) 3 0L); 
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WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_CRS, WM_ENABLE , 

MPFROMSHORT(TransmitStatus & CHAR_READY_TO_SEND_IMM), 0L); 
WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_XON, WM_ENABLE, 

MPFROMSHORT(TransmitStatus & WAITING_TO_SEND_XON), 0L) ; 
WinSendDlgltemMsg (hWnd, IDC_LINESTATUS_XOF, WM_ENABLE, 

MPFROMSHORT(TransmitStatus & WAITING_TO_SEND_XOFF), 0L); 
break; 


case WM_USER_COMEVENT: 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComEvent 
break; 

case WM_USER_COMERROR: 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComError 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComError 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComError 
WinSendDlgltemMsg (hWnd, 
MPFROMSHORT(ComError 
break; 


IDC_COMMEVENT__CTS, WM_ENABLE, 
& CTS_CHANGED), 0L); 
IDC_COMMEVENT_DSR, WM_ENABLE, 
& DSR_CHANGED), 0L); 

IDC_COMMEVENT_DCD, WM_ENABLE, 
& DCD_CHANGED), 0L); 
IDC_COMMEVENT_BRKj WM_ENABLE, 
& BREAK_DETECTED), 0L); 

IDC_COMMEVENT_ERR , WM_ENABLE, 
& ERROR_OCCURRED), 0L); 
IDC_COMMEVENT_RI, WM_ENABLE 3 
& RI_DETECTED), 0L); 


IDC_COMMERROR_QOV, WM_ENABLE, 
& RX_QUE_OVERRUN), 0L); 
IDC_COMMERROR_HOV, WM_ENABLE, 
& RX_HARDWARE_OVERRUN), 0L); 
IDC_COMMERROR_PAR, WM_ENABLE, 
& PARITY_ERROR), 0L); 
IDC_COMMERROR_FRM 3 WM_ENABLE, 
& FRAMING_ERROR), 0L); 


case WM_USER_MODEMINPUT: 

WinSendDlgltemMsg (hWnd, IDC_MODEM_CTS, WM_ENABLE, 
MPFROMSHORT(Modemlnput & CTS_ON) 3 0L); 
WinSendDlgltemMsg (hWnd, IDC_MODEM__CTS, WM_ENABLE, 
MPFROMSHORT(ModemInput & CTS_ON), 0L); 
WinSendDlgltemMsg (hWnd, IDC_MODEM_DSR, WM_ENABLE, 
MPFROMSHORT(Modemlnput & DSR_ON), 0L); 
WinSendDlgltemMsg (hWnd, IDC_MODEM_RI, WM_ENABLE, 
MPFROMSHORT(Modemlnput & RI_ON), 0L); 
WinSendDlgltemMsg (hWnd, IDC_MODEM_DCD, WM_ENABLE, 
MPFROMSHORT(Modemlnput & DCD_ON), 0L); 
break; 


case WMJJSERJVIODEMOUTPUT: 

WinSendDlgltemMsg (hWnd, IDC_MODEM_DTR, WM_ENABLE, 
MPFROMSHORT(ModemOutput.fbModemOn & DTR_ON), 0L); 
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WinSendDlgltemMsg (hWnd, IDC_MODEM_RTS, WM_ENABLE, 
MPFROMSHORT(ModemOutput. fbModemOn & RTS_0N), 0L); 
break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_CONNECT: 

ConnectToPort (hWnd); 
break; 

case IDC_HANGUP: 

HangUpFromPort (hWnd); 
break; 

case IDC_SETTINGS: 

WinDlgBox (HWND_DESKTOP 3 hWnd, SettingsDlgProc, 
0L, IDD_SETTINGS, NULL); 

break; 

case IDC_TRANSMIT: 

ToggleTransmit (hWnd); 
break; 

case IDC_ABOUT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

if (bConnected) 

WinSetFocus (HWND_DESKTOP, hWndLocalEdit); 
break; 

case WM__DESTROY: 
if (bConnected) 

HangUpFromPort (hWndButtons); 
break; 

default: 

bHandled = FALSE; 
break; 


if (IbHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 

} 
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MRESULT EXPENTRY SettingsDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

MRESULT mReturn = 0; 

BOOL bHandled = TRUE; 

switch (msg) 

{ 

case WM_INITDLG: 

CenterWindow (hWnd); 

InitializeControls (hWnd, TRUE); 
if (bConnected) 

WinEnableControl (hWnd, IDC_PORT, FALSE); 
break; 

case WM_CONTROL: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_P0RT: 

if (HIUSHORT(mpl) == CBN_EFCHANGE) 

{ 

ulPort = (ULONG)WinSendDlgltemMsg (hWnd, IDC_P0RT, 
LM_QUERYSELECTION, (MPARAM)LIT_FIRST, 0L) ; 
InitializeControls (hWnd, FALSE); 

} 

break; 

} 

break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 

case DID_OK: 

DelnitializeControls (hWnd); 
if (bConnected) 

SetPortSettings (hWnd); 

/* FALL THROUGH */ 

case DID_CANCEL: 

WinDismissDlg (hWnd, DID_OK); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 
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if (IbHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


PHONE.H 

/* 

Phone Header File 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

. */ 


#define 
#define 

FONTNAMELEN 7 /* 

HELV8F0NT ”8.Helv" 

length + 1 

/* Dialog and Control Identifiers 

*/ 

#define 

ID_APPNAME 

1 

#define 

IDD_SETTINGS 

10 

#define 

IDD_STATUS 

20 

#define 

IDD_BUTTONS 

30 

#define 

IDB_LED 

50 

#define 

IDC_P0RT 

100 

#define 

IDC_BAUDRATE 

101 

#define 

IDC_DATABITS_5 

103 

#define 

IDC_DATABITS_6 

104 

#define 

IDC_DATABITS_7 

105 

#define 

IDC DATABITS_8 

106 

#define 

IDC_ST0PBITS_1 

107 

#define 

IDC ST0PBITS__15 

108 

#define 

IDC_ST0PBITS_2 

109 

#define 

IDC_PARITY_NON E 

110 

#define 

IDC PARITY_ODD 

111 

#define 

IDC_PARITY_EVEN 

112 

#define 

IDC PARITY_MARK 

113 

#define 

IDC_PARITY_S PACE 

114 

#define 

IDC_HANDSHAKING_DTRC 

115 

#define 

IDC HANDSHAKING DTRI 

116 
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#define IDC_HANDSHAKING_CTSO 117 
#define IDC_HANDSHAKING_DSRO 118 
#define IDC_HANDSHAKING_DCD0 119 
#define IDC_HANDSHAKING_DSRI 120 
#define IDC_HANDSHAKING_RTSI 121 
#define IDC_FLOWCONTROL_XONXOFFT 122 
#define IDC_XONCHAR 123 
#define IDC_XOFFCHAR 124 
#define IDC_FLOWCONTROL_XONXOFFR 125 
#define IDC_FLOWCONTROL_ERRORREP 126 
#define IDC_FLOWCONTROL_NULLSTRIP 127 
#define IDC_FLOWCONTROL_BREAKREP 128 
#define IDC_FLOWCONTROL_RTSC 129 
#define IDC_FLOWCONTROL_TOGGLING 130 
#define IDC_ERRORREPCHAR 131 
#define IDC_BREAKREPCHAR 132 
#define IDC_TIMEOUT_WRITE 133 
#define IDC_TIMEOUT_READ 134 

#define IDC_COMMEVENT_CTS 200 
#define IDC_COMMEVENT_DSR 201 
#define IDC_COMMEVENT_DCD 202 
#define IDC_COMMEVENT_BRK 203 
#define IDC_COMMEVENT_ERR 204 
#define IDC_COMMEVENT_RI 205 
#define IDC_COMMSTATUS_CTS 206 
#define IDC_COMMSTATUS_DST 207 
#define IDC_COMMSTATUS_DCD 208 
#define IDC_COMMSTATUS_XON 209 
#define IDC_COMMSTATUS_XOF 210 
#define IDC_COMMSTATUS_BRK 211 
#define IDC_COMMSTATUS_IMM 212 
#define IDC_COMMSTATUS_DSR 213 
#define IDC_QUEUE_IN 214 
#define IDC_QUEUE_OUT 215 
#define IDC_MODEM_CTS 216 
#define IDC_MODEM_DSR 218 
#define IDC_MODEM_RI 219 
#define IDC_MODEM_DCD 220 
#define IDC_MODEM_DTR 221 
#define IDC_MODEM_RTS 222 
#define IDC_LINESTATUS_WRQ 223 
#define IDC_LINESTATUS_DTQ 224 
#define IDC_LINESTATUS_HTX 225 
#define IDC_LINESTATUS_CRS 226 
#define IDC_LINESTATUS_XON 227 
#define IDC_LINESTATUS_XOF 228 
#define IDC_LINESTATUS_RED 229 
#define IDC_LINESTATUS_WRT 230 
#define IDC_COIVIMERROR_QOV 231 
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#define IDC_COMMERROR_HOV 232 
#define XDC_COMMERROR_PAR 233 
#define IDC_COMMERROR_FRM 234 

#define IDC_CONNECT 300 
#define IDC_HANGUP 301 
#define IDC_SETTINGS 302 
#define IDC_TRANSMIT 303 
#define IDC ABOUT 304 


PHONE.RC 

/* 

Phone Resource File 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


#include <os2.h> 

#include "phone.h" 

#include "led.h" 

ICON ID_APPNAME PHONE.ICO 

BITMAP IDB_LED LED.BMP 

STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Phone Communications Application 

END 

rcinclude buttons.dig 
rcinclude settings.dig 
rcinclude status.dig 
rcinclude ..\common\about.dig 


PHONE.DEF 

NAME PHONE WINDOWAPI 

DESCRIPTION 'Phone Communications 1993 Blain, Delimon, & English' 
PROTMODE 

HEAPSIZE 4096 

STACKSIZE 16384 
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EXPORTS 


ClientWndProc 

@1 

SettingsDlgProc 

@2 

StatusDlgProc 

@3 

LEDWndProc 

@4 

AboutDlgProc 

@5 


SETTINGS.DLG 


/* 


Settings Dialog 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_SETTINGS LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Communications Settings", IDD_SETTINGS, 41, 104, 
327, 125, WS_VISIBLE, 

FCF_SYSMENU j FCF_TITLEBAR | FCF_NOBYTEALIGN 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 

LTEXT "Port", -1, 3, 112, 20, 8 

CONTROL IDC_PORT, 3, 77, 35, 35, WC_COMBOBOX, 

CBS_DROPDOWNLIST | WS_GROUP ] WS_TABSTOP | 
WS VISIBLE 


LTEXT 

CONTROL 


GROUPBOX 

AUTORADIOBUTTON 

AUTORADIOBUTTON 

AUTORADIOBUTTON 

AUTORADIOBUTTON 

GROUPBOX 

AUTORADIOBUTTON 

AUTORADIOBUTTON 

AUTORADIOBUTTON 

GROUPBOX 

AUTORADIOBUTTON 

AUTORADIOBUTTON 


"Baud Rate", -1,3, 92, 37, 8 

"", IDC_BAUDRATE, 7, 1, 44, 91, WC_SLIDER, 

SLS_VERTICAL | SLS_LEFT | 

SLS_SNAPTOINCREMENT J 
SLS_BUTTONSBOTTOM | SLS_HOMETOP | 

SLS_PRIMARYSCALE1 j WS_GROUP | WS_TABSTOP \ 
WS_VISIBLE 

CTLDATA 12, 0, 13, 0, 0, 0 
"Data Bits”, -1, 55, 100, 79, 20 
"5", IDC_DATABITS_5, 59, 102, 18, 10, WS_TABSTOP 

"6", IDC_DATABITS_6, 78, 102, 18, 10, WS_TABSTOP 

"7", IDC_DATABITS_7, 95, 102, 18, 10, WS_TABSTOP 

"8", IDC_DATABITS_8, 113, 102, 18, 10, WS_TABSTOP 

"Stop Bits", -1, 55, 75, 79, 22 
"1", IDC_STOPBITS_1, 60, 78, 18, 10, WS_TABSTOP 

"1,5",IDC_ST0PBITS_15, 84, 78, 24, 10, WS_TABSTOP 
“2", IDC_ST0PBITS_2, 114, 78, 18, 10, WS_TABSTOP 
"Parity", -1, 54, 33, 80, 38 

"None", IDC_PARITY_NONE, 58,52,33,10, WS__TABSTOP 

"Odd", IDC_PARITY_ODD, 58,43,33,10,WS_TABSTOP 
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AUTORADIOBUTTON “Even", IDC_PARITY_EVEN, 58 ,35,33,10,WS_TABSTOP 
AUTORADIOBUTTON "Mark", IDC_PARITY_MARK, 96 , 52 ,33,10,WS_TABSTOP 
AUTORADIOBUTTON "Space", IDC_PARITY_SPACE, 96,43,33,10,WS_TABSTOP 
GROUPBOX “Handshaking", -1, 139, 33, 70, 87 


AUTOCHECKBOX 

" DTR 

Control". 

i—i 

o 

o 

HANDSHAKING_ 

DTRC, 

144, 

102, 

50, 

10 

AUTOCHECKBOX 

"DTR 

Input", 

IDC_ 

"handshaking. 

~DTRI, 

144, 

92, 

50, 10 

AUTOCHECKBOX 

" CTS 

Output", 

IDC_ 

"handshaking. 

^CTSO, 

144, 

82, 

50, 

10 

AUTOCHECKBOX 

" DSR 

Output", 

I DC 

"handshaking. 

jdsro, 

144, 

72, 

50, 10 

AUTOCHECKBOX 

11 DCD 

Output", 

IDC~ 

"handshaking. 

"dodo, 

144, 

62, 

50, 

10 

AUTOCHECKBOX 

"DSR 

Input", 

IDC_ 

"handshaking. 

"dsri , 

144, 

52, 

50, 10 

AUTOCHECKBOX 

"RTS 

Input", 

IDC_ 

"handshaking. 

"rtsi, 

144, 

42, 

50, 10 


GROUPBOX "Flow Control", -1, 214, 33, 105, 87 
AUTOCHECKBOX "XON/XOFF Transmit", IDC_FLOWCONTROL_XONXOFFT, 

218, 102, 73, 10 

ENTRYFIELD IDC_XONCHAR, 295, 102, 6, 8, ES_CENTER | NOT 

ES_AUTOSCROLL | ES_MARGIN 

ENTRYFIELD IDC_XOFFCHAR, 305, 102, 6, 8, ES_CENTER | NOT 

ES_AUTOSCROLL | ES_MARGIN 

AUTOCHECKBOX "XON/XOFF Receive", IDC_FLOWCONTROL_XONXOFFR, 

218, 92, 73, 10 

AUTOCHECKBOX "Error Replacement", IDC_FLOWCONTROL_ERRORREP, 

218, 82, 73, 10 

AUTOCHECKBOX “Null Stripping", IDC_FLOWCONTROL_NULLSTRIP, 

218, 72, 73, 10 

AUTOCHECKBOX "Break Replacement", IDC_FLOWCONTROL_BREAKREP, 

218, 62, 73, 10 

AUTOCHECKBOX "RTS Control", IDC_FLOWCONTROL_RTSC, 

218, 52, 73, 10 

AUTOCHECKBOX “Toggling", IDC_FLOWCONTROL_TOGGLING, 

218, 42, 73, 10 

ENTRYFIELD "", IDC_ERRORREPCHAR, 295, 82, 6, 8, ES_CENTER | NOT 
ES_AUTOSCROLL | ES_MARGIN 

ENTRYFIELD IDC_BREAKREPCHAR, 295, 62, 6, 8, ES_CENTER ] NOT 

ES_AUTOSCROLL | ES_MARGIN 
GROUPBOX "Timeouts", -1, 54, 8, 128, 23 
LTEXT "Write", -1 , 59, 14, 20, 8 

CONTROL IDC_TIMEOUT_WRITE, 83, 12, 32, 12, WC_SPINBUTTON, 

SPBS_ALLCHARACTERS | SPBS_NUMERICONLY | 

SPBS_MASTER | 

SPBS_SERVANT | SPBS_JUSTRIGHT 1 

SPBS_FASTSPIN | WS_GROUP | WS_TABSTOP | WS_VISIBLE 
LTEXT "Read", - 1 , 119, 14, 20, 8 

CONTROL IDC_TIMEOUT_READ, 143, 12, 32, 12, WC_SPINBUTTON, 

SPBS_ALLCHARACTERS | SPBS_NUMERICONLY J SPBS_MASTER | 
SPBS_SERVANT j SPBS_JUSTRIGHT | 

SPBS_FASTSPIN \ WS_GROUP | WS_TABSTOP | WS_VISIBLE 
PUSHBUTTON "OK", DID_OK, 229, 11, 40, 14 

PUSHBUTTON "Cancel", DID_CANCEL, 279, 11, 40, 14 

END 
END 
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STATUS.DLG 

/* 

Status Dialog 
Chapter 14 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


DLGTEMPLATE IDD_STATUS LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 


DIALOG "", 

, IDD_STATUS, 41, 184, 373, 

43, 

NOT 

FSJDLGBORDER 

WS_VISIBLE, FCF_NOBYTEALIGN 
PRESPARAMS PP_FONTNAMESIZE, "B.Helv 11 
BEGIN 

GROUPBOX "Comm Event", -1, 

2, 

C\J 

119, 

19 

CONTROL 

"CTS", IDC_COMMEVENT_CTS, 

5, 

CD 

CM 

17, 

11. 

CONTROL 

LEDCLASS, WS_VISIBLE 
"DSR", IDC_COMMEVENT_DSR, 

24, 

26, 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"DCD", IDC_COMMEVENT_DCD, 

43, 

26, 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"BRK", IDC COMMEVENT BRK, 

62, 

CD 

CM 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"ERR", IDC_COMMEVENT_ERR, 

81, 

CD 

CM 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"RI", IDC_COMMEVENT_RI, 

100, 

26, 

17, 

11, 

GROUPBOX 

LEDCLASS, WS_VISIBLE 
"Comm Status", -1, 

127, 

24, 

156, 

19 

CONTROL 

"CTS", IDC_COMMSTATUS_CTS, 

130, 

26, 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"DSR", IDC_COMMSTATUS_DST, 

149, 

26, 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"DCD", IDC_COMMSTATUS_DCD, 

168, 

CD 

CM 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"XOF", IDC_COMMSTATUS_XON, 

187, 

CD 

CM 

17, 

11, 

CONTROL 

LEDCLASS, WS_VISIBLE 
"XON", IDC_COMMSTATUS_XOF, 

206, 

26, 

17, 

11 , 

CONTROL 

LEDCLASS, WS_VISIBLE 
"BRK", IDC_COMMSTATUS_BRK, 

225, 

CD 

CM 

17, 

11 , 

CONTROL 

LEDCLASS, WS_VISIBLE 
"IMM", IDC_COMMSTATUS_IMM, 

244, 

CD 

CM 

17, 

11 , 

CONTROL 

LEDCLASS, WS_VISIBLE 
"DSR", IDC_COMMSTATUS DSR, 

263, 

CD 

CM 

17, 

11 , 

GROUPBOX 

LEDCLASS, WS_VISIBLE 
"Queue", -1, 

292, 

24, 

© 

CO 

19 

LTEXT 

"Rev", -1, 

295, 

27, 

15, 

8 

LTEXT 

"0000", IDC QUEUE IN, 

311 , 

27, 

18, 

8 
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LTEXT 

"Xmt", -1, 

334, 

27, 

15, 

8 

LTEXT 

"0000", idc_queue_out, 

350, 

27, 

18, 

8 

GROUPBOX 

"Modem", -1, 

2, 

3, 

119, 

19 

CONTROL 

"CTS\ IDC_MODEM_CTS, 
LEDCLASS, WS_VISIBLE 

5, 

5, 

17, 

11. 

CONTROL 

"DSR", IDC MODEM DSR, 
LEDCLASS, WS_VISIBLE 

C\J 

5, 

17, 

11, 

CONTROL 

"RI", IDC MODEM_RI, 
LEDCLASS, WS_VISIBLE 

CO 

5, 

17, 

11, 

CONTROL 

"DCD", IDC MODEM DCD, 
LEDCLASS, WS_VISIBLE 

62, 

5, 

17, 

11, 

CONTROL 

"DTR", IDC_MODEM_DTR, 
LEDCLASS, WS_VISIBLE 

81, 

5, 

17, 

11, 

CONTROL 

"RTS", IDC_MODEM_RTS, 
LEDCLASS, WS_VISIBLE 

100, 

5, 

17, 

11, 

GROUPBOX 

"Line Status", -1, 

127, 

3, 

156, 

19 

CONTROL 

"WRQ", IDC_LINESTATUS_WRQ, 
LEDCLASS, WS_VISIBLE 

130, 

5, 

17, 

11, 

CONTROL 

"DTQ", IDC_LINESTATUS_DTQ, 
LEDCLASS, WS VISIBLE 

149, 

5, 

17, 

11, 

CONTROL 

"HTX", IDC_LINESTATUS_HTX, 
LEDCLASS, WS_VISIBLE 

168, 

5, 

17, 

11, 

CONTROL 

"CRS", IDC LINESTATUS_CRS, 
LEDCLASS, WS_VISIBLE 

187, 

5, 

17, 

11, 

CONTROL 

"XON", IDC LINESTATUS_XON, 
LEDCLASS, WS_VISIBLE 

206, 

5, 

17, 

11, 

CONTROL 

"XOF", IDC LINESTATUS_XOF, 
LEDCLASS, WS_VISIBLE 

225, 

5, 

17, 

11, 

CONTROL 

"RED", IDC_LINESTATUS_RED, 
LEDCLASS, WS_VISIBLE 

244, 

5, 

17, 

11, 

CONTROL 

"WRT", IDC_LINESTATUS_WRT, 
LEDCLASS, WS_VISIBLE 

263, 

5, 

17, 

11 , 

GROUPBOX 

"Comm Error", -1, 

292, 

3, 

80, 

19 

CONTROL 

"QOV", IDC_COMMERROR_QOV, 
LEDCLASS, WS_VISIBLE 

295, 

5, 

17, 

11 , 

CONTROL 

"HOV", IDC_COMMERROR_HOV, 
LEDCLASS, WS_VISIBLE 

314, 

5, 

17, 

11 , 

CONTROL 

"PAR", IDC COMMERROR_PAR, 
LEDCLASS, WS_VISIBLE 

333, 

5, 

17, 

11 , 

CONTROL 

"FRM", IDC_COMMERROR_FRM, 

352, 

5, 

17, 

11 , 


LEDCLASS, WS_VISIBLE 

END 

END 


BUTTONS.DLG 

/* 
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DLGTEMPLATE IDD_SETTINGS LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Communications Settings", IDD_SETTINGS, 41, 104, 

327, 125, WS_VISIBLE, 

FCF_SYSMENU j FCF_TITLEBAR | FCF_NOBYTEALIGN 
PRESPARAMS PP_FONTNAMESIZE, "8.Helv" 

BEGIN 

LTEXT "Port", -1, 3, 112, 20, 8 

CONTROL "", IDC_PORT, 3, 77, 35, 35, WC_COMBOBOX, 

CBS_DROPDOWNLIST | WS_GROUP | WS_TABSTOP | 
WS_VISIBLE 

LTEXT "Baud Rate", -1,3, 92, 37, 8 

CONTROL "", IDC_BAUDRATE, 7, 1, 44, 91, WC_SLIDER, 

SLS_VERTICAL | SLS_LEFT | 

SLS_SNAPTOINCREMENT | 

SLS_BUTTONSBOTTOM | SLSJHOMETOP | 
SLS_PRIMARYSCALE1 | WS_GROUP | WS_TABSTOP | 
WS_VISIBLE 

CTLDATA 12, 0, 13, 0, 0, 0 


GROUPBOX 

"Data 

Bits", -1, 55, 

100, 

79, 20 




AUTORADIOBUTTON 

"5", 

IDC_DATABITS_5, 

59, 

102, 

18, 

10, WS 

Q_ 

o 

1— 
CO 
CO 
< 
h- 

1 

AUTORADIOBUTTON 

"6", 

ID C_DATABITS_6, 

78, 

102, 

18, 

10, WS 

Q_ 

O 

1— 
CO 
CQ 
< 
(- 

1 

AUTORADIOBUTTON 

"7", 

I DC_DAT ABIT S_7, 

95, 

102, 

18, 

10, WS 

CL 

O 

1— 
CO 
CO 
< 
h- 

1 

AUTORADIOBUTTON 

"8", 

I DC_DAT ABIT S_8, 

113, 

102, 

18, 

10, WS 

Q_ 

O 

1— 
CO 
CO 
< 
1- 

1 

GROUPBOX 

"Stop 

Bits", -1, 55, 

75, 79, 22 




AUTORADIOBUTTON 

"1", 

IDC_STOPBITS_1 

» 60, 

78, 18, 

10 , ws_ 

TABSTOP 

AUTORADIOBUTTON 

"1.5" 

, IDC_STOPBITS_15, 84, 

78, 24, 

10 , ws_ 

TABSTOP 

AUTORADIOBUTTON 

"2", 

IDC_ST0PBITS_2 

, 114, 

78, 18, 

10 , ws_ 

TABSTOP 

GROUPBOX 

"Parity", -1, 54, 33 

, 80, 

38 




AUTORADIOBUTTON 

"None 

", IDC_PARITY_ 

NONE, 

58,52 

,33 

, 10 , ws_ 

TABSTOP 

AUTORADIOBUTTON 

"Odd" 

, IDC_PARITY_ 

ODD, 

58,43 

,33 

,10,ws_ 

TABSTOP 

AUTORADIOBUTTON 

"Even 

" , IDC_PARITY_ 

EVEN, 

58,35 

,33 

, 10,WS 

TABSTOP 

AUTORADIOBUTTON 

"Mark 

" , IDC_PARITY_ 

MARK, 

96,52 

,33 

,10, WS 

TABSTOP 


AUTORADIOBUTTON "Space", IDC_PARITY_SPACE, 96,43,33,10,WSJTABSTOP 
GROUPBOX "Flandshaking 11 , -1, 139, 33, 70, 87 


AUTOCHECKBOX 

" DTR 

Control", 

IDC_ 

HANDSHAKING 

DTRC, 

144, 

102, 

50, 

10 

AUTOCHECKBOX 

" DTR 

Input", 

IDC] 

“handshaking] 

]dtri, 

144, 

92, 

50, 

10 

AUTOCHECKBOX 

" CTS 

Output", 

IDC] 

handshaking] 

]CTS0, 

144, 

82, 

50, 

10 

AUTOCHECKBOX 

" DSR 

Output", 

IDC] 

Handshaking" 

]dsro, 

144, 

72, 

50, 

10 

AUTOCHECKBOX 

" DCD 

Output", 

IDC] 

.handshaking" 

]dcdo, 

144, 

62, 

50, 

10 

AUTOCHECKBOX 

"DSR 

Input", 

IDC~ 

handshaking" 

]dsri, 

144. 

52, 

50, 

10 

AUTOCHECKBOX 

"RTS 

Input", 

IDC" 

.handshaking" 

"rtsi, 

144, 

42, 

50, 

10 

GROUPBOX 

"Flow Control" 

, 

214, 33, 105, 87 






AUTOCHECKBOX "XON/XOFF Transmit", IDC_FLOWCONTROL_XONXOFFT, 
218, 102, 73, 10 
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ENTRYFIELD 

ES_ 

, IDC_XONCHAR, 
AUTOSCROLL | 

295, 102, 
ES_MARGIN 

6 , 

8 , 

ES_CENTER J 

NOT 

ENTRYFIELD 

ES 

, IDC_XOFFCHAR 
_AUTOSCROLL ] 

, 305, 102, 
ES_MARGIN 

6 , 

8 , 

ES_CENTER 

! NOT 


AUTOCHECKBOX "XON/XOFF Receive", IDC_FLOWCONTROL_XONXOFFR, 

218, 92, 73, 10 

AUTOCHECKBOX "Error Replacement", IDC_FLOWCONTROL_ERRORREP, 

218, 82, 73, 10 

AUTOCHECKBOX "Null Stripping", IDC_FLOWCONTROL_NULLSTRIP, 

218, 72, 73, 10 

AUTOCHECKBOX "Break Replacement", IDC_FLOWCONTROL_BREAKREP, 

218, 62, 73, 10 

AUTOCHECKBOX “RTS Control", IDC_FLOWCONTROL_RTSC, 

218, 52, 73, 10 

AUTOCHECKBOX "Toggling", IDC_FLOWCONTROL_TOGGLING, 

218, 42, 73, 10 

ENTRYFIELD IDC_ERRORREPCHAR, 295, 82, 6, 8, ES_CENTER | NOT 

ES_AUT0SCR0LL | ES_MARGIN 

ENTRYFIELD IDC_BREAKREPCHAR, 295, 62, 6, 8, ES_CENTER ] NOT 

ES_AUTOSCROLL | ES_MARGIN 
GROUPBOX "Timeouts", -1, 54, 8, 128, 23 
LTEXT "Write", -1, 59, 14, 20, 8 

CONTROL IDC_TIMEOUT_WRITE, 83, 12, 32, 12, WC_SPINBUTTON, 

SPBS_ALLCHARACTERS j SPBS_NUMERICONLY | 

SPBS_MASTER \ 

SPBS_SERVANT ; SPBS_JUSTRIGHT ] 

SPBS_FASTSPIN \ WS_GROUP ] WS_TABSTOP \ WS_VISIBLE 
LTEXT "Read", -1, 119, 14, 20, 8 

CONTROL IDC_TIMEOUT_READ, 143, 12, 32, 12, WC_SPINBUTTON, 

SPBS_ALLCHARACTERS | SPBS_NUMERICONLY | SPBS_MASTER \ 
SPBS_SERVANT | SPBS_JUSTRIGHT | 

SPBS_FASTSPIN | WS_GROUP | WS_TABSTOP | WS_VISIBLE 
PUSHBUTTON “OK", DID_OK, 229, 11, 40, 14 

PUSHBUTTON "Cancel", DID_CANCEL, 279, 11, 40, 14 

END 
END 


Understanding PHONE.C 

When the application starts, it determines the number of communications ports on the 
system and attempts to open each communications port and query the current settings 
for the port: 

VOID QueryValidCommPorts () 

{ 


780 


BYTE cCommPorts; 
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/* Determine the number of communication ports on the system */ 
DosDevConfig (&cCommPorts, DEVINF0_RS232); 
ulNumPorts = (ULONG)cCommPorts; 

/* Attempt to query current com port settings */ 
for (ullnx = 0; ullnx < ulNumPorts; ullnx++) 

{ 

szCom[3] = (CHAR)( 1 1 1 + ullnx); 

if (IDosOpen (szCom, &hFile, &ulAction, 0L, FILE_NORMAL, 

FILE_0PEN 3 OPEN_ACCESS_READWRITE ! OPEN_SHARE DENYNONE, 0L)) 

{ 

QueryBaudRate (ullnx); 

QueryDCBInfo (ullnx); 

QueryLineCtrl (ullnx); 

DosClose (hFile); 

PortInfo[ullnx].DCBInfo.usWriteTimeout = 0; 

PortInfo[ulInx].DCBInfo.usReadTimeout = 0; 

} 


The port is opened and the connection established in ConnectToPort: 


szCom[3] = (CHAR)( 1 1' + ulPort); 
if (IDosOpen (szCom, &hFile, &ulAction 3 0L, 

FILE_NORMAL ; file_open 3 OPEN_ACCESS_READWRITE ! open_share_denynone 3 

01 )) 


Once open, the current port settings are established in SetPortSettings. 

The event semaphore is created and the two threads are created: 

/* Create the event semaphore for the receive queue */ 
DosCreateEventSem ("\\sem32\\RCVQUEUE", &hevRcvQueue, 0 3 TRUE); 

/* Start the CommStatus and ReceiveData threads */ 

DosCreateThread (&StatusThreadID, (PFNTHREAD)CommStatusThread 3 0L 3 0 3 
0 x10000); 

DosCreateThread (&ReadThreadID 3 (PFNTHREAD)ReceiveDataThread, 0L, 0, 
0 x10000); 

The priority of the communications status thread is set to idle time because that is a 
lower priority than the write and read threads: 

/* Set the priority of the CommStatus thread to idle time */ 
DosSetPriority (PRTYS_THREAD , PRTYC_IDLETIME 3 0 3 StatusThreadID); 

SetPortSettings makes the calls to DosDevIOCtl: 
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BOOL bSet = 

!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETBAUDRATE, 

&PortInfo[ulPort].BaudRate, 2L, NULL, NULL, 0L, NULL) && 

!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETLINECTRL, 

&PortInfo[ulPort].LineControl, 3L, NULL, NULL, 0L, NULL) && 

!DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_SETDCBINFO, 

&PortInfo[ulPort].DCBInfo, sizeof(DCBINFO), 0L, NULL, 0L, NULL); 

When the data is ready to be transmitted, TransmitLine is called. In addition to 
adding the line to the local history list, it calls DosWrite to transmit the data. Notice that 
we surround the call to DosWrite with calls to DosEnterCritSec and DosExitCritSec 
so that we protect the port fde handle from being used by the other threads at the same 
time: 

/* Write data to the communications port */ 

DosEnterCritSec (); 

if ('DosWrite (hFile, szBuffer, ulLen, &ulBytesWritten)) 

{ 

szBuffer[ulLen-2] = '\0'; 

WinSendMsg (hWndLocalList, LM_INSERTITEM, 0L, (MPARAM)szBuffer); 

WinSetWindowText (hWndLocalEdit, ""); 

ulNumLocalLines++; 

} 

DosExitCritSec (); 

When we are ready to hang up the session, we call HangUpFromPort. The first thing 
to be done is flush both the input and output queues. This is done, not by an IOCTL_ASYNC 
call, but by using an IOCTL_GENERAL call: 

/* Flush the input and output buffers */ 

DosDevIOCtl (hFile, IOCTL_GENERAL, DEV_FLUSHOUTPUT, (PVOID)&Cmd, 1L, 
NULL, NULL, 0L, NULL); 

DosDevIOCtl (hFile, IOCTL_GENERAL, DEV_FLUSHINPUT, (PV0ID)&Cmd, 1L, 

NULL, NULL, 0L, NULL); 

We then call DosClose to close the connection, kill the other two threads, and close 
the event semaphore: 

if (IDosClose (hFile)) 

{ 

WinEnableControl (hWnd, IDC_CONNECT, TRUE); 

WinEnableControl (hWnd, IDCJHANGUP, FALSE); 

WinEnableWindow (hWndLocalEdit, FALSE); 

/* Stop the CommStatus and ReceiveData threads */ 

DosKillThread (StatusThreadID); 

DosKillThread (ReadThreadID); 
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/* Close the receive data event semaphore */ 

DosCloseEventSem (hevRcvQueue); 

bConnected = FALSE; 

} 

The ReceiveData thread is a continuous loop calling DosRead to receive data from 
the receive queue. Again, we make the call to DosRead within a critical section: 

DosEnterCritSec (); 

DosRead (hFile, szBuffer, (ULONG)sizeof(szBuffer), &ulBytesRead); 
DosExitCritSec (); 

When the carriage return character is detected, the line can be added to the remote 
history list. We call DosResetEventSem to clear the event semaphore and post a message 
to the main thread telling it that the data in szReceiveBuf f er contains a complete line 
of text. 

After posting the message, we wait for the event semaphore to be set by the main 
thread before continuing: 

/* Clear the event semaphore */ 

DosResetEventSem (hevRcvQueue, &ulEventCnt); 

WinPostMsg (hWndClient, WM_USER_RCVLIST, 0L, 0L); 

/* Wait for main message queue thread to process message */ 
DosWaitEventSem (hevRcvQueue, 1000); 

When all the data from the last DosRead has been processed, we notify the main thread 
that the data in szReceiveBuf fer contains an incomplete line of text. This is done simi¬ 
larly to the previous state: 

/* Clear the event semaphore */ 

DosResetEventSem (hevRcvQueue, &ulEventCnt); 

szReceiveBuffer[usNextPos] = '\0'; 

WinPostMsg (hWndClient, WM_USER_RCVTEXT, 0L, 0L); 

/* Wait for main message queue thread to process message */ 
DosWaitEventSem (hevRcvQueue, 1000); 

Finally, before repeating the loop, we put the thread to sleep for 0.10 seconds. 

The CommStatusThread is a continuous loop calling DosDevIOCtl to query the cur¬ 
rent state of the various communication flags. Like the other two threads, the use of the 
file handle is enclosed in a critical section: 


DosEnterCritSec (); 
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DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMEVENT, 

NULL, 0L, 0L, &NewComEvent, 2L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMSTATUS, 

NULL, 0L, 0L, &NewComStatus, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETINQUECOUNT, 

NULL, 0L, 0L, &NewReceiveQueue, sizeof(RXQUEUE), 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETOUTQUECOUNT, 

NULL, 0L, 0L, &NewTransmitQueue, sizeof(RXQUEUE), 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMINPUT, 

NULL, 0L, 0L, &NewModemInput, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETMODEMOUTPUT, 

NULL, 0L, 0L, &NewModemOutput, sizeof(MODEMSTATUS), 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETLINESTATUS, 

NULL, 0L, 0L, &NewTransmitStatus, 1L, 0L); 

DosDevIOCtl (hFile, IOCTL_ASYNC, ASYNC_GETCOMMERROR, 

NULL, 0L, 0L, &NewComError, 2L, 0L); 

DosExitCritSec (); 

Each set of flags is compared with the previous values, and a message is posted to the 
main thread indicating which set of flags has changed. The main thread then enables or 
disables the various LED windows to indicate the current state of the flags. Finally, be¬ 
fore repeating the loop, we put the thread to sleep for 0.20 seconds. 

When the main thread receives the WM_USER_RCVLIST message posted from the 
ReceiveDataThread, it adds the text in the szReceiveBuff er to the remote history list 
and posts the event semaphore so that the ReceiveDataThread can continue processing 
the data: 

/* Post the receive data event semaphore to notify the 

ReceiveData thread that we are done with szReceiveBuffer */ 
DosPostEventSem (hevRcvQueue); 

Likewise, the WM_USER_RCVTEXT is posted from the ReceiveDataThread and when 
this message is received, the text in the szReceiveBuff er is set in the remote display 
window. Again, the event semaphore is posted to allow the ReceiveDataThread to 
continue. 

The remaining portions of the code are involved with creating and positioning the 
windows and setting and querying the various controls contained in those windows. This 
application is not meant to be a complete communications program, but is meant to show 
how to use the DosDevIOCtl function for OS/2 communications and how to utilize threads 
to perform all the asynchronous activities involved with communications. However, it is 
an excellent foundation on which to build a number of useful apps. 




Miscellaneous 

Topics 


Miscellaneous Application 

We have covered a lot of topics at this point. There are several areas of OS/2 program¬ 
ming that can be useful in your applications development, although they do not neatly 
fall into any particular subject area. This chapter will cover some of these additional areas 
of interest. 
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A single application will be used for demonstrating some of the top¬ 
ics in this chapter. The “MISC” application will simply dis¬ 
play a window with menu options for each of the topics being 
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demonstrated. Each topic will discuss its menu options and a description of the portion 
of code involved. The code to display the miscellaneous application and issue the calls to 
perform the menu options is contained in the files MISC.C, MISC.H, MISC.RC, and 
MISC.DEF. The application window is shown in Figure 15.1. 


Figure 15.1- Main 
application window. 
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MISC.C 


/* 


Miscellaneous Program 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon 3 and English 


*1 


#define INCL_WIN 
#define INCL_GPI 

#include <os2.h> 

#include "misc.h" 

#include "pibtib.h" 

#include "drives.h" 

#include "filesrch.h" 

#include "sysinfo.h" 

#include "..\common\about.h" 

/* Window and Dialog Functions */ 

MRESULT EXPENTRY ClientWndProc (HWND,ULONG 3 MPARAM 3 MPARAM); 


/* Global Variables 
HAB hab; 


/ 







Chapter 15 


Miscellaneous Topics 


HWND hWndFrame, 

hWndClient; 

CHAR szTitle[64]; 

int main() 

{ 

HMQ hmq; 

QMSG qmsg; 

ULONG flFrameFlags = FCFJTITLEBAR j FCF_SYSMENU | FCF_IC0N 

FCF_SIZEBORDER | FCF_MINMAX J FCF_MENU 
FCF_SHELLPOSITION | FCF_TASKLIST; 

CHAR szClientClass[] = "CLIENT"; 

hab = Winlnitialize (0); 

hmq = WinCreateMsgQueue (hab, 0); 

WinRegisterClass (hab, szClientClass, ClientWndProc, 0, 0); 
WinLoadString (hab, 0, ID_APPNAME, sizeof(szTitle), szTitle); 

/* Create the main application window */ 

hWndFrame = WinCreateStdWindow (HWND_DESKTOP, WS_VISIBLE, 

&flFrameFlags, szClientClass, szTitle, 0, 0, ID_APPNAME, 
&hWndClient); 

while (WinGetMsg (hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg (hab, &qmsg); 

WinDestroyWindow (hWndFrame); 

WinDestroyMsgQueue (hmq); 

WinTerminate (hab); 
return (0); 


/* . Window Function . 

MRESULT EXPENTRY ClientWndProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_ERASEBACKGROUND: 
mReturn = MRFR0ML0NG(1L); 
break; 

case WM_COMMAND: 

switch (LOUSHORT(mpl)) 

{ 
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case IDM_PIBTIB: 

WinDlgBox (HWND_DESKTOP, hWnd, PIBTIBDlgProc, 
0L, IDD_PIBTIB 5 NULL); 

break; 

case IDM_DRIVES: 

WinDlgBox (HWND_DESKTOP , hWnd, DrivesDlgProc, 
0L, IDD_DRIVES, NULL); 

break; 

case IDM_FILESEARCH: 

DoFileSearch (hWnd); 
break; 

case IDM_SYSINFO: 

WinDlgBox (HWND_DESKTOP, hWnd, SyslnfoDlgProc, 
0Lj IDD_SYSINFOj NULL); 

break; 

case IDM_AB0UT: 

DisplayAbout (hWnd, szTitle); 
break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 


if (IbHandled) 

mReturn = WinDefWindowProc (hWnd,msg,mpl,mp2); 
return (mReturn); 

} 


MISC.H 


/* 


Miscellaneous Header File 
Chapter 15 
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Copyright (c) 1993 Blain, Delimon, and English 


*/ 


/* Dialog and Control Identifiers */ 



#define ID APPNAME 


1 
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#define 

IDD_PIBTIB 

2 

#define 

IDD_DRIVES 

3 

#define 

IDD_FILESEARCH 

4 

#define 

IDD_SYSINFO 

5 

#define 

IDM_SYSTEM 

100 

#define 

IDM_PIBTIB 

101 

#define 

IDM_SYSINFO 

102 

#define 

IDM_FILES 

110 

#define 

IDM_DRIVES 

111 

#define 

IDM_FILESEARCH 

112 

#define 

IDM ABOUT 

120 


MISCRC 


/* 


Miscellaneous Resource File 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#include <os2.h> 

#include "misc.h" 
#include "pibtib.h" 
#include "drives.h" 
#include "filesrch.h" 
#include "sysinfo.h" 

ICON ID APPNAME MISC.ICO 


STRINGTABLE LOADONCALL MOVEABLE 
BEGIN 

ID_APPNAME "Miscellaneous Topics Application 

END 


MENU ID_APPNAME 

{ 

SUBMENU "-System", 

{ 

MENUITEM "-Threadlnfo 
MENUITEM "-Syslnfo", 
MENUITEM " 

MENUITEM "-About...", 


IDM_SYSTEM 

IDM_PIBTIB 

IDM_SYSINFO 

-1, MIS_SEPARATOR 

IDM ABOUT 


} 
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SUBMENU "-Files", 

{ 

MENUITEM "-Drives", 
MENUITEM "-File Search", 

} 

} 

rcinclude pibtib.dlg 
rcinclude drives.dig 
rcinclude filesrch.dlg 
rcinclude sysinfo.dlg 
rcinclude ..\common\about.dig 


MISC.DEF 

NAME MISC WINDOWAPI 

DESCRIPTION 'Miscellaneous Topics 1993 Blain, Delimon, & English 
PROTMODE 

HEAPSIZE 4096 

STACKSIZE 16384 


EXPORTS 

ClientWndProc @1 
PIBTIBDlgProc @2 
DrivesDlgProc @3 
FileSearchDlgProc @4 
AboutDlgProc @5 


Obtaining Thread Information 

Every process in OS/2 consists of at least one thread of execution. It can also create addi¬ 
tional threads that execute simultaneously with the other threads of the process. All threads 
of a process execute as part of the parent process. A thread can query information about 
itself and the process to which it belongs with the DosGetlnf oBlocks function. 

APIRET APIENTRY DosGetlnfoBlocks (PTIB *pptib, PPIB *pppib); 

PTIB *pptib Address of a pointer to receive the address of the 

thread’s Thread Information Block (TIB). 

PPIB *pppib Address of a pointer to receive the address of the 

process’s Process Information Block (PIB). 
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The TIB structure returned from this function contains information specific to the 
individual thread: 

typedef struct 

{ 

PVOID tib_pexchain; 

Head of the thread's exception handler chain 
PVOID tib_pstack; 

Base address of the thread's stack 
PVOID tib_pstacklimit; 

Ending address of the thread's stack 
PTIB2 tib_ptib2; 

Pointer to TIB2 structure containing system information 
about the thread 
ULONG tib_version; 

TIB structure version number 
PVOID tib_ordinal; 

Unique thread identifier (also known as the process 
slot number) 

} TIB; 

The system information about the thread is referenced by the tib_ptib2 field of the 
TIB structure. 

typerdef struct 

{ 

ULONG tib2_ultid; 

Thread identifier 
ULONG tib2_ulpri; 

Thread priority 
ULONG tib2_version; 

TIB2 structure version number 
USHORT tib2_usMCCount; 

Count of DosEnterMustComplete calls without matching 
DosExitMustComplete calls 
USHORT tib2_fMCForceFlag; 

MustComplete force flag 

} TIB2; 

The PIB structure returned from the DosGetlnf oBlocks function contains infor¬ 
mation specific to the process and is the same for all threads of execution of the same 
process: 

typedef struct 

{ 

ULONG pib_ulpid; 

Process identifier 
ULONG pib_ulppid; 

Process identifier of parent process 
ULONG pib_hmte; 

Process's module handle 
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PCHAR pib_pchcmd; 

Address of the process' command line 
PCHAR pib_pchenv; 

Address of the process' environment block 
ULONG pib_flstatus; 

Process status flags 
ULONG pib_ultype; 

Process type 

FAPPTYP_NOTSPEC - Unknown 

FAPPTYP_NOTWINDOWCOMPAT - Not window compatible 

FAPPTYP_WINDOWCOMPAT - Window compatible 

FAPPTYP_WINDOWAPI - Window API 

} PIB; 


Retrieving process and thread information is demonstrated by selecting menu 
options System and then Threadlnfo in the Miscellaneous application. This option 
will display a dialog box containing some of the relevant process and thread information. 
See Figure 15.2. 


Figure 15.2. 
DosGetlnfoBlock 


Process Information 
dialog. 


rProcess Information fPIB}- 
Process ID 

~~7 - 

Thread Info (TIBJ 
Thread ID 

1 

Parent Process ID 

2 

Priority 

200 

Module Handle 

2FF 

Slot 

29 

Status 

10 

Stack Base 

20000 

Type 

Window API 

Stack End 

25180 


Command Line 


D:\BOOK\CHAP15\C0DE\MISC.EXE 
Environment 


iWP_OBJHANDLE= 125061 
jUSER_INI=C:\OS2\OS2.1NI 
f j S YSTEM_ INI=C: \ OS2 \ OS2 S YS. INI 



The command line and environment for the process are also displayed below the 
process and thread information. The code to retrieve this information and display the 
dialog is contained in the files PIBTIB.C, PIBTIB.H, and PIBTIB.DLG. 


PIBTIB.C 


/* 


Thread Information 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_D0S 
#define INCL WIN 
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#include <os2.h> 

#include <string.h> 

#include <stdio.h> 

#include "pibtib.h" 

/* External variables 
extern HAB hab; 

/* Local Functions 
VOID ParseEnvironment 
VOID SetNumberField 

char szProcType[4][18 

{ 

"Unknown", 

"Not Window Compat", 

"Window Compat", 

"Window API" 

}; 

/* . Local Functions . */ 

VOID ParseEnvironment (HWND hWnd, PCHAR pEnv, USHORT usCtllD) 

{ 

/* Parse the environment buffer. Each line is terminated by a NULL 
byte and the last line in the buffer includes an additional NULL 
byte */ 
while (*pEnv) 

{ 

WinSendDlgltemMsg (hWnd, usCtllD, LM_INSERTITEM, 

(MPARAM)LIT_END, pEnv); 
pEnv += strlen(pEnv) + 1; 

} 

return; 

} 

VOID SetNumberField (HWND hWnd, ULONG ulNumber, USHORT usCtllD) 

{ 

CHAR szNumber[9]; 

/* Convert number to hexadecimal string */ 
sprintf (szNumber, "%81X", ulNumber); 

/* Set the text of the control */ 

WinSetDlgltemText (hWnd, usCtllD, szNumber); 

return; 

} 

/* .. Dialog Function -.... */ 


*/ 

/* Handle to anchor block */ 

*/ 

(HWND,PCHAR,USHORT); 

(HWND,ULONG,USHORT); 

] = 
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MRESULT EXPENTRY PIBTIBDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

PPIB ppib; 

PTIB ptib; 


switch (msg) 

{ 

case WM_INITDLG: 

/* Query the thread information */ 

DosGetlnfoBlocks (&ptib, &ppib); 

SetNumberField (hWnd 3 ppib->pib_ulpid, IDC_PID); 

SetNumberField (hWnd, ppib->pib_ulppid , IDC_PPID); 
SetNumberField (hWnd 3 ppib->pib_hmte 3 IDC_MODULEHANDLE); 
SetNumberField (hWnd, ppib->pib_flstatus 3 IDC_STATUS); 
WinSetDlgltemText (hWnd, IDC_TYPE 3 

szProcType[ppib->pib_ultype & 0x03]); 

SetNumberField (hWnd, (ptib->tib_ptib2)->tib2_ultid, 

IDC_TID); 

SetNumberField (hWnd, (ptib->tib_ptib2)->tib2_ulpri 3 
IDC_PRIORITY); 

/* The OS/2 2.0 Toolkit defines this field as tib_arbpointer */ 
/* The OS/2 2.1 Toolkit defines this field as tib_ordinal */ 

SetNumberField (hWnd, (ULONG)ptib->tib_ordinal 3 IDC_SL0T) 

SetNumberField (hWnd, (ULONG)ptib->tib_pstack 3 
IDC_STACKBASE); 

SetNumberField (hWnd 3 (ULONG)ptib->tib_pstacklimit , 
IDC_STACKEND); 

WinSendDlgltemMsg (hWnd, IDC_COMMANDLINE , EM_SETTEXTLIMIT, 
MPFROMSHORT(255) 3 0L); 

WinSetDlgltemText (hWnd, IDC_COMMANDLINE , ppib->pib_pchcmd); 
ParseEnvironment (hWnd, ppib->pib_pchenv 3 IDC_ENVIRONMENT); 
break; 

case WM_SYSCOMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case SC_CLOSE: 

WinDismissDlg (hWnd, FALSE); 

bHandled = TRUE; 

break; 

} 

break; 
default: 
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bHandled = FALSE; 
break; 


if (IbHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


PIBTIB.H 

/* . 

Thread Information Header File 
Chapter 15 
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Copyright (c) 1993 Blain, Delimon, and English 

*/ 


/* Exported Function */ 

MRESULT EXPENTRY PIBTIBDlgProc (HWND,ULONG,MPARAM,MPARAM); 


/* PIBTIB Dialog Controls */ 

#define IDC_PID 200 
#define IDC_PPID 201 
#define IDCJ/IODULEHANDLE 202 
#define IDC_STATUS 203 
#define IDC_TYPE 204 
#define IDC_COMMANDLINE 205 
#define IDC_ENVIRONMENT 206 
#define IDC_TID 207 
#define IDC_PRIORITY 208 
#define IDC_SL0T 209 
#define IDC_STACKBASE 210 
#define IDC_STACKEND 211 


PIBTIB.DLG 


/* 


Thread Information Dialog 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


/ 







Real-World Programming for U3/ JL 2,1 


DLGTEMPLATE IDD_PIBTIB LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "PIBTIB - DosGetInfoBlocks", IDD_PIBTIB, 17, 13, 318, 119, 
WS_VISIBLE | NOT WS_SAVEBITS, FCF_SYSMENU | FCF_TITLEBAR j 
FCF NOBYTEALIGN 


BEGIN 


GROUPBOX 

"Process Information 

(PIB)", 


3, 

"vT 

CO 

188, 

51 

LTEXT 

"Process ID", 



7, 

CO 

00 

51, 

8 

LTEXT 

"Parent Process ID", 



7 J 

90, 

"■M 

00 

8 

LTEXT 

"Module Handle", 



7 3 

C\J 

00 

CO 

CO 

8 

LTEXT 

"Status", 


-i, 

7, 

74, 

31, 

8 

LTEXT 

"Type", 



7, 

CO 

CO 

CO 

CM 

8 

RTEXT 

"", IDC_PID, 



130, 

CO 

00 

50, 

8 

RTEXT 

"", IDC_PPID, 



130, 

90, 

50, 

8 

RTEXT 

"", IDCJ/IODULEHANDLE, 



130, 

C\J 

00 

50, 

8 

RTEXT 

"", IDC_STATUS, 



130, 

74, 

50, 

8 

RTEXT 

"", IDC_TYPE, 



30, 

CO 

CO 

150, 

8 

GROUPBOX 

"Thread Info (TIB)", 



198, 

64, 

115, 

51 

LTEXT 

"Thread ID", 



203, 

CO 

00 

42, 

8 

LTEXT 

"Priority", 



203, 

90, 

CO 

8 

LTEXT 

"Slot", 


-i, 

203, 

CM 

CO 

20 , 

8 

LTEXT 

"Stack Base", 



203, 

74, 

LO 

8 

LTEXT 

"Stack End", 


•i, 

203, 

CO 

CO 

CO 

8 

RTEXT 

"", IDC TID, 



254, 

CO 

00 

50, 

8 

RTEXT 

"", IDC PRIORITY, 



254, 

90, 

50, 

8 

RTEXT 

"", IDC_SL0T, 



254, 

CM 

00 

50, 

8 

RTEXT 

"", IDC STACKBASE, 



254, 

74, 

50, 

8 

RTEXT 

"", IDC_STACKEND, 



254, 

66 , 

50, 

8 

LTEXT 

"Command Line", 



7 j 

55, 

CO 

CO 

8 

ENTRYFIELD 

"", IDC_COMMANDLINE, 

LO 

CO 

308 

, 8, 

ES_ 

MARGIN 

i 


ES_READONLY 







LTEXT 

"Environment", 


-1, 

7 3 

35 

CO 

CO 

8 

LISTBOX 

IDC_ENVIRONMENT, 3, 

3, 308 

, 31 

1 LS_ 

HORZSCROLL 



END 

END 


Remember that the environment is a sequence of null-terminated strings followed 
by a final null byte at the end of all the strings. 


Querying System Information 

There are many system-defined values that can vary from system to system. Factors af¬ 
fecting these values include the amount of installed memory, the amount of free disk space, 
installable file systems, and the version of the operating system. Applications should be 
written to be independent of these values yet use them where applicable. For example, 
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the maximum length of a file path specification can change depending on the installed 
file systems. The system values are retrieved using the DosQuerySysInfo API. All values 
returned are unsigned long values: 

APIRET APIENTRY DosQuerySysInfo(ULONG iStart, ULONG iLast, PVOID pBuf, 
ULONG cbBuf); 

ULONG iStart Index of first system value to retrieve. 

ULONG iLast Index of last system value to retrieve. 

PVOID pBuf Address of buffer to return unsigned long values. 

ULONG cbBuf Size of buffer in bytes. 

The defined indexes and their descriptions are: 


QS V_MAX_PATH JLEN GTH 

Maximum pathname length. 

QS V_MAX_TEXT_SESSION S 

Maximum number of text sessions 
allowed. 

QSV_MAX_PM_SESSIONS 

Maximum number of PM sessions 
allowed. 

QSV_MAX_VDM_SESSIONS 

Maximum number of VDM (DOS) 
sessions allowed. 

QS V_B O OT_D RIVE 

OS/2 Boot drive identifier 
(1=A, 2=B, and so on). 

QSV_DYN_PRI_VARIATION 

Dynamic Priority Variation 
(0=Absolute, l=Dynamic). 

QSV_MAX_WAIT 

Maximum wait time (seconds). 

QSV_MIN_SLICE 

Minimum time slice (milliseconds). 

QSV_MAX_SLICE 

Maximum time slice (milliseconds). 

QSV_PAGE_SIZE 

Size of memory pages (4,096 bytes). 

QSV_VERSION_MAJOR 

OS/2 major version number. 

QSV_VERSION_MINOR 

OS/2 minor version number. 

QSV_VERSION_RE VISION 

OS/2 revision letter. 

QSV_MS_COUNT 

Number of milliseconds since 
system started. 
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QSV_TIME_LOW 

Low 32-bits of time since 1/1/70 at 
00:00:00 (seconds). 

QSV_TIME_HIGH 

High 32-bits of time since 1/1/70 at 
00:00:00 (seconds). 

QSVJTOTPHYSMEM 

Number of physical memory bytes 
in the system. 

QSV_TOTRESMEM 

Number of resident memory bytes 
in the system. This is the amount of 
committed memory currently 
loaded. 

QSV_TOTAVAILMEM 

Number of available memory bytes 
in the system. This is the total 
number of bytes that could be 
allocated as swappable. 

QSV_MAXPRMEM 

Maximum number of bytes of 
private memory available. This is the 
base address up to the current shared 
memory bottom address. 

QSV_MAXSHMEM 

Maximum number of bytes of 
shared memory available. This is the 
top address of shared memory down 
to the current private memory top 
address. 

QSV_TIMER_INTERVAL 

Timer interval (milliseconds). 

QSV_MAX_COMP_LENGTH 

Maximum length of a component of 
a pathname. 


DosQuerySysInfo retrieves a sequence of system values starting with the index in 
iStart and ending with the index in iLast. To retrieve a single value, set iStart and 
Hast to the desired index value. Retrieving all the system values is demonstrated by 
selecting the menu options System and then Syslnfo in the Miscellaneous application. 
This option will display a dialog box containing a list box with all the system value iden¬ 
tifiers and their current values. Figure 15.3 shows an example of this. 

The code to retrieve this information and display the dialog is contained in the files 
SYSINFO.C, SYSINFO.F1, and SYSINFO.DLG. These are shown in the following text. 
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Figure 153. System 
Information dialog 



MAX PATH LENGTH' 

0x00000104 



MAX TEXT SESSIONS 

0x00000010 



MAX PM SESSIONS 

0x00000010 



MAX VDM SESSIONS 

0x00000101 



BOOT DRIVE 

0x00000003 



DYN PRI VARIATION 
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.1 
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I 

PAGE SIZE 
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SYSINFO.C 

/* . 


System Information 
Chapter 15 
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Copyright (c) 1993 Blain, Delimon, and English 

*/ 


#define INCL_D0S 
#define INCLJVIN 
#define INCL_ERRORS 

#include <os2.h> 
#include <stdio.h> 
#include "sysinfo.h 


/* Local Functions */ 

VOID QueryAllValues (HWND); 

/* External variables */ 

extern HAB hab; /* Handle to anchor block */ 

CHAR szSysValues[QSV_MAX][18] = 

{ 

"MAX_PATH_LENGTH ", 

"MAX_TEXT_SESSIONS", 

"MAX_PM_SESSIOHS ", 

"MAX_VDM_SESSIONS ", 

"B00T_DRIVE 
"DYN_PRI_VARIATION", 

11 MAX_WAIT 
M MIN_SLICE 
11 MAX_SLICE 
11 PAGE_SIZE 
"VERSION_MAJOR 
"VERSION_MINOR 
"VERSION_REVISION ", 
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"MS_COUNT 

"TIME_LOW 

"TIME_HIGH 

"TOTPHYSMEM 

"TOTRESMEM 

"TOTAVAILMEM 

"MAXPRMEM 

"MAXSHMEM 

"TIMER_INTERVAL 

11 MAX_COMP_LENGTH 

}; 


/* . Local Functions . */ 

VOID QueryAllValues (HWND hWnd) 

{ 

ULONG ulValues[QSV_MAX]; 

CHAR szText[31]; 

ULONG ullnx; 

DosQuerySysInfo (QSV_MAX_PATH_LENGTH, QSVJ/IAX, &ulValues, 
sizeof(ulValues)); 

for (ullnx = 0; ullnx < QSVJ/IAX; ullnx++) 

{ 

sprintf (szText, "%17s 0x%081x", szSysValues[ullnx], 

ulValues[ulInx]); 

Winllpper (hab, 0, 0, szText); 
szText[21] = 'x'; 

WinSendDlgltemMsg (hWnd, IDC_SYSINFOLIST 3 LM_INSERTITEM, 

(MPARAM)LIT_END, szText); 

} 

return; 

} 

/* . Dialog Function . */ 

MRESULT EXPENTRY SyslnfoDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

HWND hWndListBox; 

SWP Swp; 

switch (msg) 

{ 

case WM_INITDLG: 

QueryAllValues (hWnd); 
break; 
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case WMJVINDOWPOSCHANGED: 

if (((PSWP)mpl)->fl & SWP_SH0W) 

{ 

/* Center the listbox horizontally in the window */ 
hWndListBox = WinWindowFromID (hWnd 3 IDC_SYSINFOL.IST); 
WinQueryWindowPos (hWndListBox, &Swp); 

WinSetWindowPos (hWndListBox, 0L, 

(((PSWP)mpl)->cx - Swp.cx) » 1, Swp.y, 0L, 0L, SWP_MOVE); 

} 

bHandled = FALSE; 
break; 

default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 


SYSTINFO.H 


System Information Header File 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 
. */ 


/* Exported Function */ 

MRESULT EXPENTRY SysInfoDlgProc (HWND,ULONG,MPARAM,MPARAM); 
/* Syslnfo Dialog Controls */ 

#define IDC_SYSINFOLIST 500 


SYSTINFO.DLG 


/* 


System Information Dialog 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


/ 
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DLGTEMPLATE IDD_SYSINFO LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "System Information - DosQuerySysInfo", IDD_SYSINFO, 

23, 42, 213, 86, 

WS_VISIBLE, FCF_SYSMENU J FCF_TITLEBAR | FCF_NOBYTEALIGN 

BEGIN 

LISTBOX IDC_SYSINFOLIST, 4, 3, 195, 80 

PRESPARAMS PP_FONTNAMESIZE, "10.System Monospaced" 

END 

END 


We query all the system values with a single call to DosQuerySysInf o: 
ULONG ulValues[QSV_MAX]; 

DosQuerySysInfo (QSV_MAX_PATH_LENGTH, QSV_MAX, &ulValues, 
sizeof(ulValues)); 

QSV_MAX is defined to be the number of predefined system value identifiers. 


Determining Drive Types 

Many applications need to know what drives are available and if the drive is removable, 
fixed, or remote. There is no single call in PM to retrieve this information. Several calls 
must be made. 


The DosDevConf ig API is used to retrieve information about the number of print¬ 
ers, communication ports, diskette drives, and so on. This function was used in the pre¬ 
vious chapter to retrieve the number of communication ports available: 


APIRET APIENTRY DosDevConfig(PVOID pdevinfo, ULONG item); 


PVOID 

ULONG 


pdevinfo 

item 


DEVINFO_PRINTER 

Address to return data. 
Requested item: 

Number of printers 

DEVINFO_RS232 

attached. 

Number of communi¬ 

DEVINFO_FLOPPY 

cation ports. 

Number of diskette 

DEVINFO_COPROCESSOR 

drives. 

Coprocess present. 

DEVINFO_SUBMODEL 

Submodel type of 

DEVINFCLMODEL 

computer. 

Model type of 

DEVINF 0_ADAPTER 

computer. 

Display adapter. 
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All items return a BYTE value. To determine the number of diskette drives installed 
on the system, the following call could be used: 

BYTE cDisketteDrives; 

DosDevConfig (&cDisketteDrives, DEVINF0_FL0PPY); 

The DosQueryFSAttach ATI is used to retrieve information about the attached file 
system used for each drive. To retrieve the file system type for each drive based on its 
drive letter, the following options are used: 

APIRET APIENTRY DosQueryFSAttach(PSZ pszDeviceName, ULONG ulOrdinal, 
ULONG ulFSAInfoLevel, PFSQBUFFER2 pfsqb, PULONG pcbBuffLength ); 


PSZ 

pszDeviceName 

Drive letter followed by colon 
(for example, “A:”). 

ULONG 

ulOrdinal 

OL. 

ULONG 

ulFSAInfoLevel 

FSAIL_QUERYNAME. 

PFSQBUFFER2 

pfsqb 

Pointer to FSQBUFFER2 buffer 
to receive data. 

PULONG 

pcbBuffLength 

Size of buffer pointed to by 
pfsqb. 


If the drive does not exist, ERR0R_I NVAL I D_DR IVE will be returned. 
ERROR_BUFFER_OVERFLOW is returned if the buffer is not large enough to contain all the 
returned data. If the drive is a diskette drive and there is no media in the drive, 
ERROR_DRIVE_NOT_READY will be returned. The buffer pointed to by pfsqb must at least 
be as large as the FSQBUFFER2 structure plus enough space for the three name and 
data fields returned. The FSQBUFFER2 contains the information about the attached 
file system. 

typedef struct 

{ 

USHORT iType; 

FSAT_CHARDEV - Resident character device 
FSAT_PSEUDODEV - Pseudo-character device 
FSAT_LOCALDRV - Local drive 
FSAT_REMOTEDRV - Remote drive 
USHORT cbName; 

String length of name in szName field 
USHORT cbFSDName; 

String length of name in szFSDName field 
USHORT cbFSAData; 

Length of file system attached data 
UCHAR szName[1]; 

Drive name 
UCHAR szFSDName[1]; 
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Name of the file system driver (FAT, HPFS, CDFS, etc.) 
UCHAR rgFSAData[1]; 

Data for the attached file system driver 

} FSQBUFFER2; 

The DosQueryFSAttach function call will help determine if the drive is a local or 
remote drive. It will not, however, tell you if the local drive is a fixed disk. To determine 
if the drive is removable or fixed, we must open the drive and issue either a 
DSK_BLOCKREMOVABLE or DS K_G ETDEVICE PAR AMS DosDevIOCtl request. The DosDevIOCtl 
API was first discussed in the previous chapter on communications. The same API can 
be used to issue requests to the drive. 

APIRET APIENTRY DosDevIOCtl(HFILE hDevice, ULONG category, ULONG 

function, 

PVOID pParams, ULONG cbParmLenMax, PULONG pcbParmLen, 
PVOID pData, ULONG cbDataLenMax, PULONG pcbDataLen) 


hDevice 

File handle returned from DosOpen. 

category 

Device category. 

IOCTL_DISK - Logical Disk Support. 

function 

Device function. 

pParams 

Input parameter list for function. 

cbParmLenMax 

Maximum length of data in pParams. 

pcbParmLen 

Pointer to variable to receive length of return 
parameters in pParams. 

pData 

Output data area. 

cbDataLenMax 

Maximum length of data in pData. 

pcbDataLen 

Pointer to variable to receive length of return 
parameters in pData. 


The device functions we are interested in are DSK_BLOCKREMOVABLE and 
DSK_GETDEVICEPARAMS. For the I0CTL_DSK device category, it is important to note that 
the fields pcbParmLen and pcbDataLen are required because the current CD drivers do 
not allow NULL to be used for these fields. 

DSKJ3L0CKREM0VABLE —Is block device removable? 

Input data: 

BYTE Reserved byte with value of 0. 
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Output data: 

USHORT Drive type 

0 Removable 

1 Fixed 

Example: 

BYTE cCmd = 0; 

USHORT usType = 0; 

ULONG ulParmLen = sizeof(BYTE); 

ULONG ulDataLen = sizeof(USHORT); 

DosDevIOCtl (hFile, IOCTL_DISK, DSK_BLOCKREMOVABLE, 
(PVOID)&cCmd, ulParmLen, &ulParmLen, 
(PVOID)&usType, ulDataLen, &ulDataLen, NULL); 

DSK_GETDEVICEPARAMS— Query device parameters for a drive. 


BYTE Specifies which parameter block to query. 

0 Recommended parameter block for the drive. 

1 Parameter block for current medium in the drive. 

Output data: 

BIOSPARAMETERBLOCK—Parameter block for the drive. 


typedef struct 

{ 


USHORT usBytesPerSector; 
BYTE bSectorsPerCluster; 
USHORT usReservedSectors; 
BYTE cFATs; 

USHORT cRootEntries; 

USHORT cSectors; 


BYTE bMedia; 

USHORT usSectorsPerFAT; 

USHORT usSectorsPerTrack; 

USHORT cHeads; 

ULONG cHiddenSectors; 

ULONG cLargeSectors; 

BYTE abReserved[6]; 

USHORT cCylinders; 

BYTE bDeviceType; 

DEVTYPE_48TPI 
DEVTYPE_96TPI 
DEVTYPE_35 
DEVTYPE_8SD 
DEVTYPE_8DD 
DEVTYPE_FIXED 
DEVTYPE TAPE 


Low density floppy 
High density floppy 
3 1/2" floppy 
8" single density floppy 
8" double density floopy 
Fixed disk 
Tape drive 
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DEVTYPEJJNKNOWN - Other 
0x0008 - R/W optical disk 

0X0009 - 3 1/2" 4.0MB floppy 

USHORT fsDeviceAttr; 

(Bit fields) 

0x0001 - Drive is fixed 
0x0002 - Drive can detect changes 
0x0004 - Supports addresses greater than 16MB 
} BIOSPARAMETERBLOCK; 

Example: 

BYTE cBlock = 0; 

BIOSPARAMETERBLOCK bpb; 

ULONGulParmLen = sizeof(BYTE); 

ULONGIDataLen = sizeof (BIOSPARAMETERBLOCK); 

DosDevIOCtl (hFile, IOCTLJDISK, DSK_GETDEVICEPARAMS, 

(PVOID)&cBlock, ulParmLen, &ulParmLen, 

(PVOID)&bpb, ulDataLen, &ulDataLen); 

Making calls to retrieve any drive information from a drive that is not ready will 
result in OS/2 displaying its system error message box. When you’re retrieving drive 
type information for floppy drives, you don’t want that to occur. To prevent the system 
from displaying its message box, you can call DosError: 

APIRET APIENTRY DosError(ULONG error); 

ULONG ulError 

FERRJDISABLEHARDERR Disable hard errors message box. 

FERR_ENABLEHARDERR Enable hard errors message box. 

FERR_DISABLEEXCEPTION Disable exceptions message box. 

FERR_ENABLEEXCEPTION Enable exceptions message box. 

Displaying the drive type and file system information is demonstrated by selecting 
Files and then Drives in the MISC application. See Figure 15.4. 



The code to retrieve this information and display the dialog is contained in the files 
DRIVES.C, DRIVES.H, and DRIVES.DLG. 
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DRTVES.C 


/* 


Drives 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


#define INCL_D0S 
#define INCL_DOSDEVIOCTL 
#define INCL_WIN 
#define INCL_ERRORS 

#include <os2.h> 

#include <stdio.h> 

#include <string.h> 

#include "drives.h" 

/* Local Functions */ 

VOID DisplayDrivelnfo (HWND,ULONG); 

VOID FormatNumberField (HWND,USHORT,ULONG); 

VOID QueryDiskSpace (ULONG,PULONG,PULONG,PULONG); 

VOID QueryVolumeLabel (ULONG,PSZ); 

/* External variables */ 

extern HAB hab; /* Handle to anchor block */ 

/* Global variables */ 

DRIVEINFO Drivelnfo[26]; /* Array of drive information */ 

ULONG ulNumDrives = 0L; /* Number of valid drives */ 

char szDriveDescription[11][16] = 

{ 

"LD Floppy", 

"HD Floppy", 

"3.5\" Floppy", 

"8\" SD Floppy", 

"8\" HD Floppy", 

"Fixed Disk", 

"Tape Drive", 

"Unknown", 

"R/W Optical", 

"3.5\" 4MB Floppy", 

"Not Ready", 

}; 
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/* .-.. Local Functions -- */ 

VOID DisplayDrivelnfo (HWND hWnd, ULONG ullnx) 

{ 

CHAR szVolumeLabel[12]; 

ULONG ulTotalSpace, 
ulAllocated, 
ulAvailable; 

WinSetDlgltemText (hWnd, IDC_LOCATION, 

DriveInfo[ulInx].szLocation); 

WinSetDlgltemText (hWnd, IDC_REMOVABLE, 

DriveInfo[ullnx].szRemovable); 

WinSetDlgltemText (hWnd, IDC_FILESYSTEM 3 
DriveInfo[ullnx].szFileSystem); 

WinSetDlgltemText (hWnd, IDC_DESCRIPTION, 

szDriveDescription[DriveInfo[ulInx].ulDescriptionlndex]); 

WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP,SPTR_WAIT,FALSE)); 

QueryVolumeLabel (Drivelnfo[ulInx].szDrive[0] - 'A 1 +1, 
szVolumeLabel); 

WinSetDlgltemText (hWnd, IDC_V0LUMELABEL, szVolumeLabel); 

QueryDiskSpace (DriveInfo[ulInx].szDrive[0] - 'A' +1, 
&ulTotalSpace, &ulAllocated, &ulAvailable); 

FormatNumberField (hWnd, IDC_TOTALSPACE, ulTotalSpace); 

FormatNumberField (hWnd, IDC_ALLOCATED, ulAllocated); 
FormatNumberField (hWnd, IDC_AVAILABLE, ulAvailable); 

WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP,SPTR_ARROW,FALSE)); 

return; 

} 

VOID FormatNumberField (HWND hWnd, USHORT usCtllD, ULONG ulNumber) 

{ 

CHAR szNumber[13]; 

sprintf (szNumber, "%121u", ulNumber); 

WinSetDlgltemText (hWnd, usCtllD, szNumber); 
return; 

} 

VOID QueryDiskSpace (ULONG ulDriveNumber, PULONG pulTotalSpace, 
PULONG pulAllocated, PULONG pulAvailable) 
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FSALLOCATE fsAllocate; 

DosError (FERR_DISABLEHARDERR); 

if (!DosQueryFSInfo (ulDriveNumber, FSIL_ALLOC, &fsAllocate, 
sizeof(FSALLOCATE))) 

{ 

*pulTotalSpace = 

fsAllocate. cSectorllnit * fsAllocate. cllnit * 
fsAllocate.cbSector; 

*pulAvailable = 

fsAllocate.cSectorUnit * fsAllocate.cUnitAvail * 
fsAllocate.cbSector; 

*pulAllocated = *pulTotalSpace - *pulAvailable; 

} 

else 

*pulTotalSpace = *pulAllocated = *pulAvailable = 0L; 
DosError (FERR_ENABLEHARDERR); 
return; 

} 

VOID QueryVolumeLabel (ULONG ulDriveNumber, PSZ pszVolumeLabel) 

{ 

FSINFO fslnfo; 

DosError (FERR_DISABLEHARDERR); 

if (IDosQueryFSInfo (ulDriveNumber, FSIL_VOLSER, &fsInfo, 
sizeof(FSINFO))) 

strcpy (pszVolumeLabel, fslnfo.vol.szVolLabel); 
else 

pszVolumeLabel[0] = '\0 1 ; 

DosError (FERR_ENABLEHARDERR); 
return; 

} 

VOID QueryDrives (HWND hWnd) 

{ 

PFSQBUFFER2 pfsq2; 

ULONG ulLen, 

ullnx, 
ulAction, 
ulParmLen, 
ulDataLen; 


809 



Real-World Programming for 2.1 


APIRET RetCode; 

HFILE hFile; 

BIOSPARAMETERBLOCK bpb; 

CHAR szDrive[3] = " 

BYTE cBlock = 0; 

WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP,SPTR_WAIT,FALSE)); 

/* Allocate buffer */ 

DosAllocMern ((PPV0ID)&pfsq2, 1024L, fALLOC); 

DosError (FERR_DISABLEHARDERR); 
ulNumDrives = 0L; 

for (ullnx = 0; ullnx < 26; ullnx++) 

{ 

szDrive[0] = (CHAR)('A' + ullnx); 
ulLen = 1024L; 

RetCode = DosQueryFSAttach (szDrive, 0L, FSAIL_QUERYNAME, pfsq2, 
&ulLen); 

DriveInfo[ulNumDrives].szDrive[0] = szDrive[0]; 

DrivelnfofulNumDrives].szDrive[1] = 1 \0'; 

if (RetCode == ERROR_NOT_READY) 

{ 

/* Assume local, removable, and FAT file system */ 
strcpy (DriveInfo[ulNumDrives].szLocation, "Local"); 

strcpy (DriveInfo[ulNumDrives].szRemovable, "Yes"); 
strcpy (DriveInfo[ulNumDrives].szFileSystem, "FAT"); 
DriveInfo[ulNumDrives].ulDescriptionlndex = 10L; 
ulNumDrives++; 

} 

else if (RetCode != ERROR_INVALID_DRIVE) 

{ 

bpb.fsDeviceAttr = 0; 

/* Attempt to open the device */ 
if (IDosOpen (szDrive, &hFile, &ulAction, 0L, 

FILE_NORMAL, FILE_0PEN, 

OPEN_FLAGS_DASD | OPEN_SHARE_DENYNONE, 0L)) 

{ 

ulParmLen = sizeof(BYTE); 

ulDataLen = sizeof(BIOSPARAMETERBLOCK); 

DosDevIOCtl (hFile, IOCTL_DISK, DSK_GETDEVICEPARAMS, 
(PVOID)&cBlock, ulParmLen, &ulParmLen, 

(PV0ID)&bpb, ulDataLen, &ulDataLen); 
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DosClose (hFile); 

} 

else 

{ 

/* Remote drives may not allow themselves to be opened 
with the 0PEN_FLAGS_DASD access flag. Default to 
not removable and description of unknown. */ 
bpb.fsDeviceAttr = 0x0001; 
bpb.bDeviceType = 7; 

} 

/* Is the drive remote? */ 

if (pfsq2->iType == FSAT_REMOTEDRV) 

strcpy (DriveInfo[ulNumDrives].szLocation, "Remote"); 
else 

strcpy (DriveInfo[ulNumDrives].szLocation, "Local"); 

/* Is the drive removable? */ 
if (bpb.fsDeviceAttr & 0x0001) 

strcpy (DriveInfo[ulNumDrives].szRemovable, "No"); 
else 

strcpy (DriveInfo[ulNumDrives].szRemovable, "Yes"); 

/* Set the description index */ 
if (bpb.bDeviceType < 10) 

Drivelnfo[ulNumDrives].ulDescriptionlndex = 

(LONG)bpb.bDeviceType; 

else 

DriveInfo[ulNumDrives].ulDescriptionlndex = 7L; 

/* Set the file system name */ 

strncpy (Drivelnfo[ulNumDrives].szFileSystem, 

(PSZ)(pfsq2->szName + 1 + pfsq2->cbName), 15); 

ulNumDrives++; 

} 

} 

DosError (FERR_ENABLEHARDERR); 

DosFreeMem (pfsq2); 

/* Add items to the drive listbox */ 

for (ullnx = 0; ullnx < ulNumDrives; ullnx++) 

WinSendDlgltemMsg (hWnd, IDC_DRIVELIST, LM_INSERTITEM, 
(MPARAM)LIT_END, Drivelnfo[ullnx].szDrive); 
WinSendDlgltemMsg (hWnd, IDC_DRIVELIST, LM_SELECTITEM, 0L, 
(MPARAM)TRUE); 
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WinSetPointer (HWND_DESKTOP, 

WinQuerySysPointer (HWND_DESKTOP,SPTR_ARROW,FALSE)); 
return; 


/* . Dialog Function . 

MRESULT EXPENTRY DrivesDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 

{ 

BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 

switch (msg) 

{ 

case WM_INITDLG: 

QueryDrives (hWnd); 
break; 

case WM_C0NTR0L: 

switch (LOUSHORT(mpl)) 

{ 

case IDC_DRIVELIST: 

if (HIUSHORT(mpl) == CBN_EFCHANGE) 

{ 

DisplayDrivelnfo (hWnd, 

(ULONG)WinSendDlgltemMsg (hWnd, IDC_DRIVELIST, 
LM_QUERYSELECTION, (MPARAM)LIT_FIRST, 0L)); 

} 

break; 

} 

break; 

case WM_SYSCOMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case SC_CL0SE: 

WinDismissDlg (hWnd, FALSE); 

bHandled = TRUE; 

break; 

} 

break; 
default: 

bHandled = FALSE; 
break; 


if (!bHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
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return (mReturn); 

} 


DRIVES. H 


/* 


Drives Header File 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 


*/ 


/* Exported Function */ 

MRESULT EXPENTRY DrivesDlgProc (HWND,ULONG,MPARAM,MPARAM); 

VOID QueryDrives (HWND); 

typedef struct 

{ 

CHAR szDrive[2]; 

CHAR szLocation[7]; 

CHAR szRemovable[4]; 

CHAR szFileSystem[16]; 

ULONG ulDescriptionlndex; 

} DRIVEINFO; 


/* Drives Dialog Controls */ 

#define IDC_DRIVELIST 300 
#define IDC_LOCATION 301 
#define IDC_REMOVABLE 302 
#define IDC_FILESYSTEM 303 
#define IDC_DESCRIPTION 304 
#define IDC_VOLUMELABEL 305 
#define IDC_TOTALSPACE 306 
#define IDC_ALLOCATED 307 
#define IDC_AVAILABLE 308 


DRJVRS.DLG 

/* 

Drives Dialog 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 
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DLGTEMPLATE IDD_DRIVES LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 


DIALOG 

"Drive List", 

IDD_DRIVES, 39, 

, 74, 

, 186, 82, WS_VISIBLE 

BEGIN 

FCF_SYSMENU | 

FCF_TITLEBAR j 

FCF_ 

NOBYTEALIGN 

LTEXT 

"Drive", 

-1, 3, 

68, 

22, 8 


CONTROL , IDCJDRIVELIST, 4, 4, 22, 63, WC_COMBOBOX, 



CBS_DROPDOWNLIST ! WS_GROUP 

WS 

TABSTOP ! WS VISIBLE 

LTEXT 

"Location:", -1, 

OO 

CD 

CD 

CO 

43,' 

8 



LTEXT 

"Removable?", -1, 

36, 60, 

58, 

8 



LTEXT 

"File System:", -1, 

36, 52, 

58, 

8 



LTEXT 

"Description:", -1, 

36, 44, 

54, 

8 



LTEXT 

"Volume Label:", -1, 

36, 36, 

62, 

8 



ENTRYFIELD 

"", IDCJ.OCATION, 

99, 68, 

81, 

8, 

ES_ 

RIGHT 1 


ES_READONLY | NOT WS_ 

TABSTOP 





ENTRYFIELD 

"", IDC_REMOVABLE, 

99, 60, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS 

JABSTOP 





ENTRYFIELD 

"", IDC_FILESYSTEM, 

99, 52, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

JABSTOP 





ENTRYFIELD 

"", IDC_DESCRIPTION,~ 

99, 44, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

TABSTOP 





ENTRYFIELD 

"", IDC_VOLUMELABEL,” 

"99, 36, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

JABSTOP 





LTEXT 

"Total Space:", -1, 

36, 24, 

58, 

8 



LTEXT 

"Allocated:", -1, 

36, 16, 

46, 

8 



LTEXT 

"Available:", -1, 

36, 8, 

45, 

8 



ENTRYFIELD 

"", IDC_TOTALSPACE, 

99, 24, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

JABSTOP 





ENTRYFIELD 

"", IDC_ALLOCATED, 

99, 16, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

JABSTOP 





ENTRYFIELD 

"", IDC_AVAILABLE, 

99, 8, 

81, 

8, 

ES_ 

RIGHT | 


ES_READONLY | NOT WS_ 

TABSTOP 






END 

END 


The QueryDrives function is responsible for determining all the valid drive letters 
and querying the type of file system installed on each. It begins by allocating a buffer to 
contain the file system data and disabling the system error handling. 

/* Allocate buffer */ 
ulLen = 1024L; 

DosAllocMem ((PPV0ID)&pfsq2, ulLen, fALLOC); 

DosError (FERR_DISABLEHARDERR); 

Following these calls, the code attempts to query the file system data for each pos¬ 
sible drive letter, as follows: 
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szDrive[0] = (CHAR)('A 1 + ullnx); 

RetCode = DosQueryFSAttach (szDrive, 0L, FSAIL_QUERYNAME, pfsq2, 

&ulLen); 

If no error code is returned from this call, you then need to query the drive. In order 
to make the call to DosDevIOCtl, you need to have a file handle. However, you are que¬ 
rying the drive, not a file. How do you get a file handle for a drive? You use the 
OPEN_FLAGS_DASD flag of the DosOpen API. This flag enables you to open a drive and 
treat it as an open file. After the drive has been opened and you have the file handle, you 
call DosDevIOCtl to query the device parameters for the drive: 

if (IDosOpen (szDrive, &hFile, &ulAction, 0L, 

FILE_NORMAL, FILE_0PEN, OPEN_FLAGS_DASD | OPEN_SHARE_DENYNONE, 0L)) 

{ 

ulParmLen = sizeof(BYTE); 

ulDataLen = sizeof(BIOSPARAMETERBLOCK); 

DosDevIOCtl (hFile, IOCTLJDISK, DSK_GETDEVICEPARAMS, 

(PVOID)&cBlock, ulParmLen, &ulParmLen, 

(PVOID)&bpb, ulDataLen, &ulDataLen); 

DosClose (hFile); 

} 

else 

{ 

/* Remote drives may not allow themselves to be opened 
with the OPEN_FLAGS_DASD access flag. Default to 
not removable and description of unknown. */ 
bpb.fsDeviceAttr = 0x0001; 
bpb.bDeviceType = 7; 

} 

The DosOpen call may fail when attempting to open remote drives using the 
OPEN_FLAGS_DASD flag. If the open fails, you simply assume that the drive is not remov¬ 
able and set the drive description to “unknown.” After all drives have been queried, the 
system error handling is enabled and the temporary buffer is freed: 

DosError (FERR_ENABLEHARDERR); 

DosFreeMem (pfsq2); 

When you know the valid drive letters and the type of file system installed for each 
drive, you might also want to know the volume label and disk space utilization for a drive. 
Both types of information can be retrieved by using the DosQueryFSInf o API: 

APIRET APIENTRY DosQueryFSInfo(ULONG disknum, ULONG infolevel, PVOID 
pBuf,ULONG cbBuf); 

ULONG disknum - Logical drive number to query (0=current drive, 1=A, 
2=B, etc) 
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ULONG infolevel - Type of drive informatino to retrieve 

FSIL_ALLOC - Level 1 (disk utilization) 
FSIL_VOLSER - Level 2 (volume information) 

PVOID pBuf - Pointer to buffer to return requested information 

ULONG cbBuf - Size of buffer pointed to by pBuf 

For FSIL_ALLOC requests, the buffer pointed to by pBuf is an FSALLOCATE structure: 

typedef struct _FSALLOCATE 

{ 

ULONG idFileSystem; 

File System identifier 
ULONG cSectorUnit; 

Number of sectors per allocation unit 
ULONG cUnit; 

Number of allocation units 
ULONG cUnitAvail; 

Number of available allocation units 
USHORT cbSector; 

Number of bytes per sector 

} FSALLOCATE; 


The QueryDiskSpace function in DRIVES.C demonstrates how to query the disk 
utilization and calculate the total amount of disk space allocated, the amount of disk space 
available, and the amount of disk space in use: 


VOID QueryDiskSpace 

{ 


(ULONG ulDriveNumber, PULONG pulTotalSpace, 
PULONG pulAllocated, PULONG pulAvailable) 


FSALLOCATE fsAllocate; 


DosError (FERR_DISABLEHARDERR); 

if (!DosQueryFSInfo (ulDriveNumber, FSIL_ALLOC, &fsAllocate, 
sizeof(FSALLOCATE))) 

{ 

*pulTotalSpace = 

fsAllocate.cSectorUnit * fsAllocate.cUnit * 
fsAllocate.cbSector; 

*pulAvailable = 

fsAllocate.cSectorUnit * fsAllocate.cUnitAvail * 
fsAllocate.cbSector; 

*pulAllocated = *pulTotalSpace - *pulAvailable; 

} 

else 

*pulTotalSpace = *pulAllocated = *pulAvailable = 0L; 
DosError (FERR_ENABLEHARDERR); 


return; 

> 
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For FSIL_VOLSER requests, the buffer pointed to by pBuf is an FSINFO structure: 

typedef struct 

{ 

BYTE cch; 

String length of volume label 
CFIAR szVoll_abel[12]; 

Volume label 
} VOLUMELABEL; 

typedef struct 

{ 

ULONG ulVSN; 

Volume serial number 
VOLUMELABEL vol; 

Volume label structure 

} FSINFO; 

The QueryVolumeLabel function in DRIVES.C demonstrates how to query the 
volume label for a drive: 

VOID QueryVolumeLabel (ULONG ulDriveNumber, PSZ pszVolumeLabel) 

FSINFO fslnfo; 

DosError (FERR_DISABLEHARDERR); 

if (IDosQueryFSInfo (ulDriveNumber, FSIL_VOLSER, &fsInfo, 
sizeof(FSINFO))) 

strcpy (pszVolumeLabel, fslnfo.vol.szVolLabel); 
else 

pszVolumeLabel[0] = 1 \ 0 1 ; 

DosError (FERR_ENABLEHARDERR); 
return; 

} 


File Searching 

Searching for files can be done in many ways. Perhaps the easiest way is to utilize a set of 
PM functions specifically designed for this purpose. Three functions, DosFindFirst, 
DosFindNext, and DosFindClose are used to search a specific directory for any and all 
files matching a specified search criteria. Two nice features of these functions is that the 
file specification need only be specified once, and support is provided for recursively search¬ 
ing subdirectories. 
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To begin a search, the DosFindFirst API is used. In this call, the file specification is 
provided and a “snapshot” of the directory is taken. This “snapshot” is a list of all files in 
the specified directory that match the file specification. Although this API can be used to 
search not only for filenames but also for extended attributes, we are only concerned with 
filenames now. The DosFindFirst API has the following format when used to search 
only for files: 


APIRET APIENTRY DosFindFirst(PSZ pszFileSpec, PHDIR phdir, ULONG 

flAttribute,PVOID pfindbuf, ULONG cbBuf, PULONG pcFileNames, 
ULONG ulInfoLevel ); 


PSZ pszFileSpec 
PHDIR phdir 


ULONG flAttribute 


File path or filename to search (may contain wild cards). 

Address of handle associated with this search request. 

On input, the values for this handle may be: 

HDIR_SYSTEM Reusable handle for 

any search. 

HDIR_CREATE Unique handle created 

for this search (used 
for nested or recursive 
searches). 


File attributes to search for: 
FILE_NORMAL 

FILE_READONLY 

FILEJHIDDEN 

FILE_SYSTEM 

FILEJDIRECTORY 

FILE_ARCHIVED 

MUSTJHAVE_READONLY 

MUSTJHAVEJHIDDEN 

MUST_HAVE_SYSTEM 

MUSTJHAVE_DIRECTORY 

MUST_HAVE_ARCHIVED 


File with no attribute 
bits set. 

Include readonly files. 
Include hidden files. 
Include system files. 
Include directory files. 
Include archived files. 
Must have readonly 
attribute. 

Must have hidden 
attribute. 

Must have system 
attribute. 

Must be a directory. 
Must have archived 
attribute. 


PVOID pfindbuf Address of buffer to receive file list entries. 

ULONG cbBuf Size of buffer pointed to by pfindbuf. 

PULONG pcFileNames On input, number of file entries to return in buffer. 

On output, number of file entries placed in buffer. 
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ULONG ulInfoLevel Requested file information level. 

FIL_STANDARD File information only 

(no extended attribute 
data). 

If you do not need to perform a recursive or nested search (that is, search another 
directory while a search of a directory is currently in progress); then you can set the search 
request handle to HDIR_SYSTEM. Otherwise, you must use the HDIR_CREATE handle. Each 
call to DosFindFirst using the HDIR_CREATE handle will create a unique handle for 
that search. The returned data in the buffer referenced by pf indbuf is in the form of 
a FILEFINDBUF3 structure: 

typedef struct 

{ 

ULONG oNextEntryOffset; 

Reserved for system use 
FDATE fdateCreation; 

Date of file creation 
FTIME ftimeCreation; 

Time of file creation 
FDATE fdateLastAccess; 

Date file was last accessed 
FTIME ftimeLastAccess; 

Time file was last accessed 
FDATE fdateLastWrite; 

Date file was last written 
FTIME ftimeLastWrite; 

Time file was last written 
ULONG cbFile; 

Size of file 
ULONG cbFileAlloc; 

Allocated size of file 
ULONG attrFile; 

File attributes 
UCHAR cchName; 

String length of the file name 
CHAR achName[CCHMAXPATHCOMP]; 

File name 
} FILEFINDBUF3; 

The achName field contains the file’s name as it exists in the directory. It is not a 
complete pathname of the file. Normally, file searching is performed one file at a time. 
However, it is possible to retrieve multiple FILEFINDBUF3 structures with each call. By 
setting the cbBuf field to the number of entries to retrieve on input and defining the 
buffer to be large enough to contain those entries, the call will attempt to return that 
many entries in the buffer. The cbBuf field will be updated with the actual number of 
entries placed in the buffer. 
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To begin a search for files that must have the readonly attribute, the following call 
could be used: 

FILEFINDBUF3 FindBuf3; 

HDIR hDir = HDIR_CREATE; 

ULONG ulFileCount = 1L; 

if (!DosFindFirst (szFullPath, &hDir, FILE_MUST_HAVE_READONLY, 

&FindBuf3, sizeof(FILEFINDBUF3), &ulFileCount, FIL_STANDARD)) 

After the file search has begun, DosFindNext is used to repeatedly return the next 
file from the search “snapshot”: 

APIRET APIENTRY DosFindNext(HDIR hdir, PVOID pfindbuf, 

ULONG cbfindbuf, PULONG pcFilenames ); 

HDIR hDir Search handle from DosFindFirst call. 

PVOID pfindbuf Address of buffer to receive file list entries. 

ULONG cbfindbuf Size of buffer pointed to by pfindbuf. 

PULONG pcFileNames On input, number of file entries to return in 

buffer. 

On output, number of file entries placed in 
buffer. 

Like the DosFindFirst call, it is possible to request multiple files to be retrieved with 
each call. The hDir parameter must be the matching search handle for the DosFindFirst 
call. 

When the directory search is complete, it is necessary to call DosFindCloseto termi¬ 
nate the search and release any resources being used by the system to maintain the search 
handle: 

APIRET APIENTRY DosFindClose(HDIR hDir); 

HDIR hDir—Search handle from DosFindFirst call. 

Performing a file search is demonstrated by selecting the menu options Files and then 
File Search in the Miscellaneous application. Figure 15.5 shows how this might appear 
on a typical system. 

Figure 15.5. 

File Search dialog. 
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Our file search will simply search for a file, or files matching a wild card specification 
on a specific drive. It will recursively search subdirectories finding all occurrences. This 
implementation will also make use of multithreading to perform the search in a separate 
thread. Because searching may be a time-consuming process, it is a good idea to put that 
processing in a separate thread so that the user can continue performing other tasks in 
the application while the search is proceeding. The code to perform the file searching 
and to display the dialog is contained in the files FILESRCH.C, FILESRCH.H, and 
FILESRCH.DLG. 

FILESRCH.C 

/* . 

File Search 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright (c) 1993 Blain, Delimon, and English 

*/ 

#define INCL_DOS 
#define INCL_DOSFILEMGR 
#define INCL_WIN 
#define INCL_ERRORS 

#include <os2.h> 

#include <string.h> 

#include "misc.h" 

#include "drives.h" 

#include "filesrch.h" 

/* Thread Function */ 

VOID SearchThread (HWND); 

/* Local Functions */ 

VOID SearchForFile (HWND); 

VOID SetControlStates (HWND); 

VOID StartSearch (HWND); 

VOID StopSearch (VOID); 

/* External variables */ 

extern HAB hab; /* Handle to anchor block */ 

extern DRIVEINFO Drivelnfof]; 
extern ULONG ulNumDrives; 

/* Global variables */ 

TID SearchThreadID; /* Thread ID of Search thread*/ 

CHAR szFileName[CCHMAXPATHCOMP]; /* Filename to search */ 

CHAR szFullPath[CCHMAXPATH] = " :\\; /* File path buffer */ 

HWND hWndFileSearch = 0; /* File search dialog window */ 

BOOL bSearching = FALSE; /* Search in progress flag */ 
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/* . Search Thread Function . */ 

/* 

The Search thread is responsible for searching the selected disk 
for the specified filename. This function will search all 
subdirectories starting with the directory in szFullPath. 

The field IDC_CURRENTDIR is updated with the name of each 
directory that is being searched. Each matching filename is 
added to the IDC_DIRLIST listbox. 

Since this thread will be directly updating the dialog box control 
windows, it must create a message queue. Thus, it will be a 
Message queue thread. 

The thread is automatically terminated when all subdirectories 
have been search or when the bSearching flag is reset. 

*/ 

#ifdef IBMC 

#pragma linkage(SearchThread, system) 

#endif 

VOID SearchThread (HWND hWnd) 

{ 

HMQ hmqThread; 

HAB habThread; 

/* Create message queue for this thread */ 
habThread = Winlnitialize (0); 
hmqThread = WinCreateMsgQueue (hab, 0); 

bSearching = TRUE; 

SetControlStates (hWnd); 

/* Perform the search */ 

SearchForFile (hWnd); 

bSearching = FALSE; 

SetControlStates (hWnd); 

/* Destroy the message queue for this thread */ 

WinDestroyMsgQueue (hmqThread); 

WinTerminate (habThread); 

DosExit (EXIT_THREAD, 0L); 

} 
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/* . Local Functions .. */ 

VOID SearchForFile (HWND hWnd) 

{ 

HDIR hDir = HDIR_CREATE; 

ULONG ulDirPos = strlen (szFullPath); 

ULONG ulFileCount = 1L; 

FILEFINDBUF3 FindBuf3; 

/* Check for filename length overflow */ 
if ((ulDirPos + strlen(szFileName)) > CCHMAXPATH) 
return; 

WinSetDlgltemText (hWnd, IDC_CURRENTDIR, szFullPath); 

/* Search for all files in directory matching the filename */ 
strcat (szFullPath, szFileName); 

if (IDosFindFirst (szFullPath, &hDir, FILEJMORMAL, &FindBuf3, 
sizeof(FILEFINDBUF3), &ulFileCount, FIL_STANDARD)) 

{ 

do 

{ 

szFullPath[ulDirPos] = '\0‘; 

strncat (szFullPath, FindBuf3.achName, CCHMAXPATH); 
WinSendDlgltemMsg (hWnd, IDC_DIRLIST, LM_INSERTITEM, 

(MPARAM)LIT_END, szFullPath); 
ulFileCount = 1L; 

} 

while (bSearching && 

!DosFindNext (hDir, &FindBuf3, sizeof(FILEFINDBUF3), 
&ulFileCount)); 

DosFindClose (hDir); 

} 

/* Has the user cancelled the searching? */ 
if (!bSearching) 
return; 

/* For each subdirectory in this directory call SearchForFile */ 

szFullPath[ulDirPos] = '\0 1 ; 

strcat (szFullPath, "*.*"); 

ulFileCount = 1L; 

hDir = HDIR_CREATE; 

if (IDosFindFirst (szFullPath, &hDir, MUST_HAVE_DIRECTORY, 

&FindBuf3, sizeof(FILEFINDBUF3), &ulFileCount, FIL_STANDARD)) 

{ 

do 

{ 

if (!strcmp(FindBuf3.achName, ". 11 ) || 

!strcmp(FindBuf3.achName, "..")) 
continue; 
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/* Check for path name length overflow */ 
if ((ulDirPos + FindBuf3.cchName + 1) >= CCHMAXPATH) 
continue; 

szFullPath[ulDirPos] = '\0'; 

strcat (szFullPath, FindBuf3.achName); 

strcat (szFullPath, "\\"); 

SearchForFile (hWnd); 
ulFileCount = 1L; 

} 

while (bSearching && 

IDosFindNext (hDir, &FindBuf3, sizeof(FILEFINDBUF3), 
&ulFileCount)); 

DosFindClose (hDir); 

} 

return; 

} 

VOID SetControlStates (HWND hWnd) 

{ 

/* Show the searching fields */ 

WinShowWindow (WinWindowFromID (hWnd, IDC_SEARCHING), bSearching); 
WinShowWindow (WinWindowFromID (hWnd, IDC_CURRENTDIR), bSearching); 

/* Disable filename and drivelist input controls */ 
WinEnableControl (hWnd, IDC_FILENAME, !bSearching); 

WinEnableControl (hWnd, IDC_DRIVELIST, !bSearching); 

/* Change button text */ 

WinSetDlgltemText (hWnd, IDC_SEARCH, 
bSearching ? "Stop" : "Search"); 

return; 

} 

VOID StartSearch (HWND hWnd) 

{ 

ULONG ullnx; 

/* Get file spec to search */ 

WinQueryDlgltemText (hWnd, IDC_FILENAME, sizeof(szFileName), 
szFileName); 
if (!szFileName[0]) 

{ 

DosBeep (750, 200); 
return; 

} 
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/* Get drive selection and start at the root directory */ 
ullnx = (ULONG)WinSendDlgltemMsg (hWnd, IDC_DRIVELIST, 

LM_QUERYSELECTION, (MPARAM)LIT_FIRST, 0L); 
szFullPath[0] = DriveInfo[ulInx].szDrive[0]; 
szFullPath[3] = 1 \0'; 

/* Clear the directory listbox */ 

WinSendDlgltemMsg (hWnd, IDCJ3IRLIST, LM_DELETEALL, 0L, 0L); 

/* Start the search thread */ 

DosCreateThread (&SearchThreadID, (PFNTHREAD)SearchThread, 

(ULONG)hWnd, 0, 0x10000); 

return; 

} 

VOID StopSearch () 

{ 

/* Signal search thread to stop */ 
bSearching = FALSE; 

/* Don't attempt to call DosWaitThread here. Doing so will hang 

the process because when the search thread returns from the initial 
call to SearchForFile, it will call SetControlStates. The call 
to WinShowWindow, for example, will attempt to send a message to 
the control window's owner and since the main thread would be 
blocked waiting for the search thread, the message could not be 
sent and the search thread would block. 

The thread will terminate as soon as it sees the bSearching 
flag has been set to FALSE. */ 

return; 

} 

/* .-. Dialog Function .. */ 

VOID DoFileSearch (HWND hWnd) 

{ 

if (!hWndFileSearch) 

hWndFileSearch = WinLoadDlg (HWND_DESKTOP, hWnd, 

FileSearchDlgProc, 0L, IDD_FILESEARCH, NULL); 

else 

WinSetActiveWindow (HWND_DESKTOP, hWndFileSearch); 
return; 

} 

MRESULT EXPENTRY FileSearchDlgProc (HWND hWnd, ULONG msg, MPARAM mpl, 

MPARAM mp2) 
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BOOL bHandled = TRUE; 

MRESULT mReturn = 0; 
switch (msg) 

{ 

case WM_INITDLG: 

QueryDrives (hWnd); 

WinShowWindow (WinWindowFromID (hWnd, IDC_SEARCHING), FALSE); 
WinShowWindow (WinWindowFromID (hWnd, IDC_CURRENTDIR), FALSE) 
WinSendDlgltemMsg (hWnd, IDC_FILENAME 3 EM_SETTEXTLIMIT 3 
MPFROMSHORT(CCHMAXPATHCOMP) 3 0L); 
break; 

case WM_COMMAND: 
case WM_SYSCOMMAND: 

switch (SHORT1FROMMP(mpl)) 

{ 

case IDC_SEARCH: 
if (bSearching) 

StopSearch (); 

else 

StartSearch (hWnd); 
break; 

case SC_CLOSE: 
if (bSearching) 

StopSearch (); 

WinDestroyWindow (hWnd); 
bHandled = TRUE; 
break; 

default: 

bHandled = (msg == WM_COMMAND); 

} 

break; 

case WM_DESTROY: 

hWndFileSearch = 0; 
break; 

default: 

bHandled = FALSE; 
break; 

} 

if (IbHandled) 

mReturn = WinDefDlgProc (hWnd, msg, mpl, mp2); 
return (mReturn); 

} 
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FILESRCH.H 

/* . 

File Search Header File 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright © 1993 Blain, Delimon, and English 

*/ 


/* Exported Function */ 

MRESULT EXPENTRY FileSearchDlgProc (HWND,ULONG,MPARAM,MPARAM); 
VOID DoFileSearch (HWND); 

/* FileSearch Dialog Controls */ 


#define 

IDC_DRIVELIST 

300 

#define 

IDC_FILENAME 

400 

#define 

IDC_DIRLIST 

401 

#define 

IDC_CURRENTDIR 

402 

#define 

IDC_SEARCHING 

403 

#define 

IDC_SEARCH 

404 

FILESRCH.DLG 



/* 


File Search Dialog 
Chapter 15 

Real-World Programming for OS/2 2.1 
Copyright 1993 Blain, Delimon, and English 


*/ 


DLGTEMPLATE IDD_FILESEARCH LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 


DIALOG "File Search", IDD_FILESEARCH, 57, 35, 239, 93, WS_VISIBLE, 


FCF 

BEGIN 

SYSMENU | FCF_TITLEBAR | 

FCF_NOBYTEALIGN 


LTEXT 

"Filename", -1, 

. 4, 

81, 

44, 

8 

ENTRYFIELD 

" ", IDC_FILENAME, 

49, 

00 

<s> 

97, 

8, ESJ/IARGIN 

LTEXT 

"Search Drive", -1 , 

, 152, 

80, 

CO 

LO 

9 

CONTROL 

"", IDC_DRIVELIST, 

211, 

CD 

21, 

CO 


WC_COMBOBOX, CBS_DROPDOWNLIST | WS_GR0UP | 
WS_TABSTOP ] WS_VISIBLE 


LTEXT 

"Directories" 

. -1, 4, 

70, 

48, 

8 

LISTBOX 

IDC_DIRLIST, 

4, 

20, 

227, 

50, 


LS_HORZSCROLL 

| NOT WSTABSTOP 



LTEXT 

"Searching", 

IDC_SEARCHING, 

. 3, 

10, 

44 j 
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LTEXT " 11 , IDC_CURRENTDIR, 4, 2, 189, 8 

PUSHBUTTON "Search", IDC_SEARCH, 194, 1, 40, 14 

END 
END 


The main application code will call DoFileSearch when the File Search menu op¬ 
tion is selected. Because the file search dialog will be a modeless dialog, this function will 
ensure that only one file search dialog is present. During the WM_INITDLG processing, we 
call the QueryDrives function from the previous section to enumerate the available drives 
and insert the entries into the drive list combo box. In the filename entry field, the filename 
to search is entered. For example, to search for all executable files on the drive, you would 
enter *.EXE. Notice that we have not added any code to remove leading spaces, so your 
entry must not include any leading spaces when searching for files on a FAT file system. 

The variable bSearching is used to indicate if a search is presently underway. The 
text of the Search button will be changed to read “Stop” while a search is being performed. 
When the Search button is pressed, the StartSearch function is called to start the search 
thread: 

VOID StartSearch (HWND hWnd) 

{ 

ULONG ullnx; 

/* Get file spec to search */ 

WinQueryDlgltemText (hWnd, IDC_FILENAME, sizeof(szFileName), 
szFileName); 
if (!szFileName[0]) 

{ 

DosBeep (750, 200); 
return; 

} 

/* Get drive selection and start at the root directory */ 
ullnx = (ULONG)WinSendDlgltemMsg (hWnd, IDC_DRIVELIST, 

LM_QUERYSELECTION, (MPARAM)LIT_FIRST, 0L); 
szFullPath[0] = DriveInfo[ulInx].szDrive[0]; 
szFullPath[3] = '\0 1 ; 

/* Clear the directory listbox */ 

WinSendDlgltemMsg (hWnd, IDC_DIRLIST, LM_DELETEALL, 0L, 0L); 

/* Start the search thread */ 

DosCreateThread (&SearchThreadID, (PFNTHREAD)SearchThread, 

(ULONG)hWnd, 0, 0x10000); 

return; 

} 
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This function simply retrieves the input filename, sets the starting drive path specifi¬ 
cation, clears the list box, and creates the search thread. When the Stop search button is 
pressed, the function StopSearch is called. This function simply sets the bSearching 
flag to FALSE. The search thread will recognize this flag change and stop the search pro¬ 
cess. Taking a look at the search thread, we see that we need to create a message queue 
thread because this thread will be sending messages to the main thread. 

/* Create message queue for this thread */ 
habThread = Winlnitialize (NULL); 
hmqThread = WinCreateMsgQueue (hab, NULL); 

It then calls the SearchForFile function, which actually performs the file search. 
Upon return from SearchForFile, the message queue is destroyed and the thread 
terminated: 

/* Perform the search */ 

SearchForFile (hWnd); 

/* Destroy the message queue for this thread */ 

WinDestroyMsgQueue (hmqThread); 

WinTerminate (habThread); 

DosExit (EXIT_THREAD, 0L); 

All the real work is performed in the SearchForFile function. The search handle, 
hDir, is declared locally so that recursive calls to SearchForFile for each subdirectory 
will create its own unique search handle. The current path and file specification are built 
by concatenating the filename to the current directory path: 

strcat (szFullPath, szFileName); 

The search is then performed on that directory, and each entry is added to the dialog’s 
list box: 

if (IDosFindFirst (szFullPath, &hDir, FILEJMORMAL, &FindBuf3, 
sizeof(FILEFINDBUF3), &ulFileCount, FIL_STANDARD)) 

{ 

do 

{ 

szFullPath[ulDirPos] = '\ 0 ‘; 

strncat (szFullPath, FindBuf3.achName, CCHMAXPATH); 
WinSendDlgltemMsg (hWnd, IDC_DIRLIST, LM_INSERTITEM, 

(MPARAM)LIT_END, szFullPath); 
ulFileCount = 1L; 

} 

while (bSearching && 

!DosFindNext (hDir, &FindBuf3, sizeof(FILEFINDBUF3), 
&ulFileCount)); 

DosFindClose (hDir); 

} 
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Notice that our loop termination also includes a check of the bSearching flag be¬ 
cause the user may have cancelled the search operation. This would be our signal to ter¬ 
minate early. After all files have been found in this directory, we must then repeat the 
process for each subdirectory found in this directory. To do this, we begin another search, 
but this time we use the MUST_HAVE_DIRECTORY file attribute so that we retrieve only 
directory entries: 

/* For each subdirectory in this directory call SearchForFile */ 

szFullPath[ulDirPos] = 1 \0 1 ; 

strcat (szFullPath, 

ulFileCount = 1L; 

hDir = HDIR_CREATE; 

if (!DosFindFirst (szFullPath, &hDir, MUST_HAVE_DIRECTORY, 

&FindBuf3, sizeof(FILEFINDBUF3), &ulFileCount, FIL_STANDARD)) 

{ 

do 

{ 

if (!strcmp(FindBuf3.achName, j | 

!strcmp(FindBuf3.achName, 

continue; 

/* Check for path name length overflow */ 
if ((ulDirPos + FindBuf3.cchName + 1) >= CCHMAXPATH) 
continue; 

szFullPathfulDirPos] = 1 \0‘; 

strcat (szFullPath, FindBuf3.achName); 

strcat (szFullPath, " \\"); 

SearchForFile (hWnd); 
ulFileCount = 1L; 

} 

while (bSearching && 

!DosFindNext (hDir, &FindBuf3, sizeof(FILEFINDBUF3), 
&ulFileCount)); 

DosFindClose (hDir); 

} 


For each entry found, we rebuild the path of the directory and call SearchForFile, 
again checking the bSearching flag after each directory search. 
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mapping to different physical addresses, 
501 

passing 

across 64K boundaries, 694-695 

from 32 to 16-bit code, 693-695 


virtual memory, 692 
alignment 

data elements in structures, 697-698 
double word, 697-698 
word, 697-698, 713 
ALLOCATE.DLG dialog file, 471-473 
AllocateDlgProc function, 472 
allocating memory, 423-426 
committed, 469 
shared, 434-435 
uncommitted, 469 
angle of rotation, 334 
anonymous semaphores, 647 
APIs 

address-converting, 696-697 
Dosl6FlatToSel, 696-697 
Dosl6SelToFlat, 696 
Dos32FlatToSel, 696-697 
Dos32SelToFlat, 696 
DosAllocMem, 426-427, 473 
DosAllocSharedMem, 434-435 
DosDevConfig, determining drive 
types, 802-803 
DosDevIOCtl, 804, 815 
DosFindClose, 820 
DosFindFirst, 818-819 
DosFindNext, 820 
DosFreeMem, 428, 440, 473 
DosGetNamedSharedMem, 435-436 
DosGetSharedMem, 436-438 
DosGiveSharedMem, 438-439 
DosOpen, 815 

DosQueryFSAttach, determining drive 
types, 803-804 
DosQueryFSInfo, 815-816 
DosQueryMem, 429-430, 451-452, 
472 

DosQuerymem, 435 
DosQuerySysInfo, system values, 
797-798 

DosSetMem, 427-430, 435, 471 





DosSubAllocMem, 432-433 
DosSubFreeMem, 433 
DosSubSet, 440 
DosSubSetMem, 431-432 
DosSubUnsetMem, 433, 440 
Memory Manager, 426-430 
profile management, 374-382 
spooler 

print jobs, tracking, 586-588 
replacement, determining, 589-591 
WinDrawBorder, 533 
application elements, defining with 
resource files, 27-28 
application names, INI files, 374 
application windows, APPSAMP, 490 
application-initiated messages, 16 
applications 

APPSAMP, 486-490 
CONTROL, 126-130, 157-176 
INITOR, 376-379,382-410 
MEMMAP, 442-452 
MEMORY, 452-473 
messages, 15-18 
“MISC”, 785-830 
phone, 736-784 
PMDRAW, 285-304 
PMFONT, 340-370 
Presentation Manager, 31 
print, 582-586 
PRNT, 592-612 
sample 

About box, 5 
building, 4-9 
installing, 4 

SKELETON, 6-9, 19-26 
thermometer, 510-562 
thread demonstration, 660-689 
Thunk, 700-715 
see also programs 
APPSAMP application 
application window, 490 


APPSAMP.C file, 488-490 
APPSAMP.DEF file, 486 
APPSAMP.H file, 486-487 
APPSAMP.RC file, 487 
APPSAMP2 program, 494-499 
APPSAMP2.C file, 494-497 
building, 486-490 
areas (graphics) 
bundles, 260 

ptlRefPoint field, 263 
usSet field, 263 
usSymbol field, 263 
fill methods, 272-274 
flags, 273 

Arrangelcons function, 120 

ascent (characters), 316 

assembler, data conversion instructions, 

694 

assembler files, TF1UNKASM.ASM, 
709-712 

ASYNC (Asynchronous Communications) 
device driver, 717-736 
Extended Hardware Buffering, 720 
flow control, 721 

ASYNC_GETBAUDRATE function, 729 
ASYNC_GETCOMMERROR function, 
733 

ASYNC_GETCOMMEVENT function, 

733- 734 

ASYNC_GETCOMMSTATUS function, 
730-731 

ASYNC_GETDCBINFO function, 

734- 736 

ASYNC_GETINQUECOUNT function, 
732 

ASYNC_GETLINECTRL function, 
729-730 

ASYNC_GETLINESTATUS function, 

731 

ASYNC_GETMODEMINPUT function, 

732 






ASYNC_GETMODEMOUTPUT 
function, 731-736 

ASYNC_GETOUTQUECOUN function, 
733 

ASYNC.SETBAUDRATE function, 723 
AS YN C_S ETB REAKO F F function, 

724- 725 

AS YN C_S ETB REAKON function, 726 
ASYNC_SETDCBINFO function, 
727-729 

ASYNC_SETLINECTRL function, 
723-724 

ASYNC_SETMODEMCTRL function, 

725- 726 

ASYNC_STARTTRANSMIT function, 
726 

ASYNC_STOPTRANSMIT function, 

726 

ASYNC_TRANSMITIMM function, 724 
attaching 

menu items, 203-205 
options to system menu, 228-229 
attributes 

files, MUST_HAVE_DIRECTORY 
file attribute, 830 
PS handle settings, 252 


backward compatibility, DLLs, 485 
base memory, 451 
baselines (fonts), 316, 334 
baud rate, 720 
queries, 729 
setting, 723 
BEGIN keyword, 29 
BEVEL control, 510 
BEVEL windows, 510, 532-534 
BEVELCLASS class, 513-515 
BEVELCLASS control, 551 


bevels 

creating, 514-515 
defining, 560 
styles, 513 

BevelWndProc function, 532 
bitmaps 

checkmarks (menu items), 207-211 
menu items, 212-214 
resizing, 211 
bits 

data, see data bits 
stop, see stop bits 
BOOK application 
BOOK16 DLL, 701 
BOOK16.C file, 701 
BOOK16.DEF file, 701 
BOOK16.FI file, 702, 708 
Booklnfo command, 700 
Booklnfo dialog, 700 
book information dialog box, 708 
BOOKINFO.DLG file, 703-704 
break characters, 312, 724-726 
BSEDOS.H header file, 435 
BSEMEMF.fi header file, macros, 435 
building 

DLLs, 480-491 
sample applications, 4-9 
variables, INSTANCEDATA, 503-504 
bundles 

area, 260, 263 
attributes, 262 
character, 260-264 
color specification, 266 
image, 260 

line, 261, 264-265 

marker, 261, 265-266 
BUTTONS.DLG file, 778-780 
BVM_SETCOLOR message, 533 
BYPOS suffix, 186 







c 

C runtime library functions, 507 
cached micro PSs 

retained graphics in, 251 
WinBeginPaint function, 254 
WinGetPS function, 254 
CalculatePercentage function, 535 
calculating 

positions of windows, 58 
window size, 59 
CALL instructions, 479 
CallCenterWIndow function, 498 
CallFillWindow function, 498 
calling 

16-bit code from 32-bit code, 698-715 
functions, FillWindow, 491 
thunks, WM_INITDLG message, 
708-709 

carriage return characters, 750 
CascadeChildWindows function, 121 
cascaded menus, 178 
cells (fonts), 316 

CenterWindow function, 469-470, 480, 
484, 532 

ChangeAccessRights function, 471 
ChangeCommitState function, 471 
changing 
fonts, 150 
icons, 78 

menu item checkmarks, 206-212 
parent windows, 14 
window focus, 61 
character bundles, 260, 263 
current setting review, 338 
fields and flags, 339 
fxBreakExtra field, 264 
fxExtra fiels, 264 
modifying, 337 
ptlAngle field, 264 
ptlShear field, 264 


sizfxCell field, 264 
structure, 337-340 
usDirection field, 264 
usPrecision field, 264 
usSet field, 264 
usTextAlign field, 264 
character mode, setting, 336 
character reference point, 309, 312 
characters 

altering spacing, 312 
ascent, 316 

break, turning off/on., 724-725 
carriage return, 750 
descent, 316 
modes, 336 

null characters, filtering, 721 
output direction, 335 
shear, 337 
XON/XOFF, 721 
checking parity, 720 
checkmarks (menu items) 
bitmaps, 207-209 
changing, 206-212 
child processes, 634 
child windows, 12-14 
classes 

BEVELCLASS, 513-515 
priority, threads, 635-636 
THERMOMETERCLASS, 515-516 
client area (windows), 15 
clrBack specifier, 147 
clrFore specifier, 147 
code pages, 308 

converting strings to/from, 340 
retrieving, 339 
code points (fonts), 307 
codes 

converting addresses, 695-697 
external function, 479 
INITOR application, 382-410 
MEMMAP application, 451-452 













MEMORY application, 469-473 
colors 

creating tables, 266 
RGB mode, 266 
RGB value, 266 
specification, 266 
thermometer, modifying, 561 
combo boxes, 149 
commands 

Add New Application, 379 
Booklnfo, 700 
FSALLOCATE, 816 
FSINFO, 817 

IDM_KILLALLTHREADS, 684 
IDMJNfEWMSGTHREAD, 683 
IDMJNEWSORTINGTHREAD, 683 
INSTALL, 4 
PMGPI, 508 
PMWIN, 508 
SET COMPILER, 5 
TIMESLICE, 637 
committed memory 
allocating, 469 
determining, 429-430 
committed pages 

access rights, changing, 428 
pages, memory, 423-426 
common dialog, 125-130, 313-329 
CommStatusThread, 748, 783 
communications 
asynchronous, 718 
hardware settings, 720-721 
status thread, 739, 781 
compilers 

compatibility, 3 
pragma statements, 697-698 
resource compilers, 29 
selecting, 5 

component files, SKELETON application, 
19-20 

components (menus), 179-184 


concatenating filenames, 829 
CONTROL application, 157-176 
File menu 

Basic Open command, 126 
Custom Open Template command, 
128 

Open and Display command, 
126-127 

Save As command, 128-129 
Font menu, 128 

Change Font command, 129-130 
Modeless Change Font, 130 
header file, 176 
required files, 157 
resource file, 175 
controls 

BEVEL, 510 
BEVELCLASS, 551 

initializing 

spinner, 560-561 
thermometer, 560 
LED, defining, 739-743 
THERMOMETER, 510 
CONTROLS.C file, 517-531 
CONTROLS.DLL, DEF file, creating, 
516 

CONTROLS.H file, 512-513 
conventions, semaphore, 647 
conversion functions, 340 
converting 
addresses 

16-bit selector to 32-bit function, 

697 

16-bit to 32-bit, 694 

32-bit function to 16-bit selector, 

697 

32-bit to 16-bit, 693-695 
queries, 588-591 

ConvertToSharedMemory function, 

441-442 

coordinates (GPI), 259-260 










copying submenus to multiple menus, 
227-228 

create_print_DC function, 586 
CreateSortingThread function, 683 
CreateThreadWindow function, 682 
creating 

accelerator tables, 27 
application messages, 87 
custom file open dialog, 139-141 
custom menu items, 214-218 
custom templates, 138-141 
DCs, 257-259 

dialog templates, 28 
file dialog, 132-133 
font dialog, 142-155 
fonts, 27, 329-334 
icons, 27, 32, 77 
logical color tables, 266 
MDI applications, 87-118 
menu applications, 27, 184-185, 
203-212 
handles, 203 
header file, 198-199 
MENU.DEF file, 201-202 
MENU.RC file, 200-201 
MENUXTRA.H file, 199-200 
necessary files, 187-188 
message queues, 25 
PSs, 251-253 

SKELETON application, 24 
string tables, 27 
submenus, 184, 203-205 
window templates, 28 
windows, 20-24, 33 
critical sections, 643-644 
CS_CLIPCHILDREN class style, 39 
CS_CLIPSIBLINGS class style, 39 
CS_FRAME class style, 39 
CS_HITTEST class style, 39 
CS JVfOVENOTIFY class style, 39 
CS_PARENTCLIP class style, 39 


CS_SAVEBITS class style, 39 
CS_SIZEREDRAW class style, 39 
CS_SIZEREDRAW style flag, 138 
CS_SYNCPAINT class style, 39 
CTLINIT.ASM file, 517-524 
custom menu items, 214-218 
custom messages, 87 
custom templates, requirements, 138 

D 

data bits, 720 

data conversion macros, 693-694 
DATA MULTIPLE NONSHARED 
process, 502-504 
data sharing problems, 643 
DATA SINGLE SHARED process, 
501-505 

DATA statement, 482-483 
data structure, windows, 54-57 
DBCS (double-byte character sets), 306 
DCs (device contexts), 251 
capabilities, 259 
creating, 257-259, 574-582 
for windows, 257 
handles, 257 
printer devices, 568 
queued, 579 
retrieving, 257-259 
DDLs (Dynamic Link Libraries), 31 
deactivating windows, 61 
debug terminal, phone application, 737 
decommitted memory pages, 423 
DEF files 

CONTROLS.DLL, 516 
DLLSAMP.DEF, 482 
format, 482- 485 
MEMDLL. DLL, 536-537 
default attributes table (PSs), 278-283 
default fonts, 309 
defining 

functions, 485 









instance data, 502 
definition space (fonts), 334 
deleting 

entries, INITOR application, 382 
semaphores from muxwait semaphores, 
660 

dependency files, 8 
descent (characters), 316 
DESCRIPTION keyword, 31 
designing threads, 645-646 
desktop window, 12 

HWNDJDESKTOP identifier, 46 
HWND_OBJECT identifier, 45 
destroying 

message queues, 25 
windows, 20-24, 33 
DestroyThreadWindow function, 682 
DEVESC_ABORTDOC escape, 582 
DEVESC_ENDDOC escape, 582, 586 
DEVESC_NEWFRAME escape, 582 
DEVESC_STARTDOC escape, 582 
DevEscape function, 582 
device contexts, see DCs 
device drivers 

ASYNC, 721-736 
private, 588 

device forms, querying, 577 
device functions 

DSK_BLOCKREMOVABLE, 

804-805 

DSK_GETDEVICEPARAMS, 

804-806 

device independence, printing, 564-565 
DEVICEINFO structure, 584 
DevOpenDC function, 252, 257, 568, 
575-576, 585, 588 

DevPostDeviceModes function, 572-574, 
585 

DevQueryCaps function, 259, 574-579 
DevQueryHardcopyCaps function, 577 


dialog boxes 

job properties, 585 
phone application, 737-738 
print, 584-586 
queue thread, 661-662 
dialog files 

ALLOCATE.DLG, 471-473 
BOOKINFO.DLG, 703-704 
BUTTONS.DLG, 778-780 
DRIVES.DLG, 813-814 
FILESRCH.DLG, 827-828 
MEMMAP.DLG, 450 
MEMORY.DLG, 471-473 
PIBTIB.DLG, 795-796 
PRNT.DLG, 592-595 
SETTINGS.DLG, 775-776 
SORT.DLG, 665 
STATUS.DLG, 777-778 
SYSTINFO.DLG, 801-802 
THERMO.DLG, 549-562 
TID.DLG, 664-665 
dialog manager styles, 40 
dialog templates, 28 
DIALOG.H file, 595-596 
dialogs 

book information, 708 
Booklnfo, 700 
modeless, 828 

Queue And Printer Details, 577 
disabled windows, 53, 61 
disabling segment packing, 695 
disk space, calculating, 816 
dispatch priority, threads, 635-636 
dispatching messages, 83 
DLLINST.C file, 503-504 
DLLINST.H file, 503 
DLLs (dynamic link libraries), 475-480 
backward compatibility, 485 
BOOK16, 701 
building, 480-491 















DosResetEventSem function, 649 
DosResumeThread function, 642 
DosSetMem API, 427-430, 433, 471 
DosSetPriority function, 640-641 
DosSleep function, 642, 686 
DOSSUB_SERIALIZE flag, 432, 439 
DosSubAllocMem API, 432-433 
DosSubFreeMem API, 433 
DosSubSet API, 440 
DosSubSetMem API, 431-432 
DosSubUnsetMem API, 433, 440 
DosSuspendThread function, 642 
DosWaitEventSem function, 650-651 
DosWaitMuxWaitSem function, 657-658 
DosWaitThread function, 644-645 
DosWrite function, 722 
double word alignment, 697-698 
double-byte character sets, see DBCS, 306 
DPDM_QUERYJOBPROP flag, 574 
DRAW.C, 286-297 
DRAW.H, 285-286 
DRAW.RC, 298 
drawing, 268-277 
primitives, 249 
routines, 157 
windows, 46 
drivers 
device 

ASYNC, 720-736 
private, 588 
printer, 564-565 
drives 

determining types, 802-817 
volume labels, 815-816 
DR1VES.C file, 807-813 
DRIVES.DLG file, 813-814 
DRIVES.H file, 813 
DSK_BLOCKREMOVABLE device 
function, 804-805 

DSK_GETDEV1CEPARAMS device 
function, 804-806 


dynamic link libraries, see DLLs 
dynamic linking 
runtime, 492-499 
versus static linking, 478-480 
DYNAMIC priority, 636 

enabled windows, 52 
enabling menu items, 205-206 
END keyword, 29 
entries 

adding, INITOR application, 379-381 
deleting, INITOR application, 382 
system initialization files, 415-418 
enum_key_name function, 378 
enumerating windows, 48 
enumeration, 314-329 
error messages 

ERROR_BUFFER_OVERFLOW, 803 
ERROR_DRIVE_NOT_READY, 803 
ERROR_INVALID_DRIVE, 803 
errors, transmission, 721 
escapes 

DEVESC_ABORTDOC, 582 
DEVESC_ENDDOC, 582, 586 
DEVESC_NEWFRAME, 582 
DEVESC__STARTDOC, 582 
event semaphores, 647-651, 783 
exitlist handlers, 507-509 
EXPENTRY keyword, 481 
EXPORT keyword, 31 
export statements, 484 
ExtDeviceMode function (Windows 3.x), 
571-572 

Extended Ffardware Buffering, 720 
external functions, codes, 479 


f IStyleMask specifier, 147 
f IStyle specifier, 146 


flType specifier, 146 
flTypeMask specifier, 146 
FamilyNameAtom field, 327 
fAttrs specifier, 148 
FATTRS structure, 329-331 
FCF_NOMOVEWITHOWNER flag, 60 
FDS_APPLYBUTTON specifier, 133 
FDS_CENTER specifier, 133 
FDS_CUSTOM specifier, 133 
FDS_ENABLEFILELB specifier, 134 
FDS_FILTERUNION specifier, 134 
FDS_HELPBUTTON specifier, 133 
FDS_INCLUDE_EAS specifier, 134 
FDS_MODELESS specifier, 134 
FDS_MULTIPLESEL specifier, 134 
FDS_PRELOAD_VOLINFO specifier, 
134 

FILEDLG structure 

FDS_APPLYBUTTON specifier, 133 
FDS_CENTER specifier, 133 
FDS_CUSTOM specifier, 133 
FDS_ENAB LEFILELB specifier, 134 
FDS_FILTERUNION specifier, 134 
FDS_HELPBUTTON specifier, 133 
FDS_INCLUDE_EAS specifier, 134 
FDS_MODELESS specifier, 134 
FDS_MULTIPLESEL specifier, 134 
FDS_PRELOAD_VOLINFO specifier, 
134 

HMODULE hMod specifier, 135 
initializing, 150 

LONG IReturn specifier, 134 
LONG 1SRC specifier, 134 
papszFQFilename specifier, 136 
papszIDriveList specifier, 135 
papszITypeList specifier, 135 
pfnDlgProc specifier, 135 
pszIDrive specifier, 135 
pszIType specifier, 135 
pszOKButton specifier, 135 
pszTitle specifier, 135 


SHORT sEAType specifier, 136 
SHORT x specifier, 136 
SHORT y specifier, 136 
szFullFile specifier, 136 
ulFQFCount specifier, 136 
ULONG ulUser specifier, 134 
usDlgld specifier, 136 
FILEDLG structure (file dialog), 133-136 
FILEFINDBUF3 structure, 819 
files 

ALLOCATE.DLG, 471-473 
APPSAMP.C, 488-490 
APPSAMP.DEF, 486 
APPSAMP.H, 486-487 
APPSAMP.RC, 487 
APPSAMP2.C, 494-497 
attributes, 830 
BOOK16.C, 701 
BOOK16.DEF, 701 
BOOK16.H, 702, 708 
BOOKINFO.DLG, 703-704 
BUTTONS.DLG, 778-780 
CONTROLS.C, 517-531 
CONTROLS.H, 512-513 
CTLINIT.ASM, 517-524 
DEF 

creating, 516 

format, 482-485 
MEMDLL. DLL, 536-537 
dialog, 131-141, 149-150 
API entries, 131 
combo boxes, 149 
creating, 132-133 
DIALOG.H, 595-596 
DLLINST.C, 503-504 
DLLINST.H, 503 
DLLSAMP.C, 480-481 
DLLS AMP. DEF, 482 
DLLSAMP.H, 482, 494 
DRIVES.C, 807-813 
DRIVES.DLG, 813-814 






DRIVES.H, 813 
FILESRCH.C, 821-826 
FILESRCH.DLG, 827-830 
FILESRCH.H, 827 
handles, 815 
header 

BSEDOS.H, 435 

BSEMEMF.H, 435 
INI 

private, 412-413 

spooler functions, 413-418 
INI, 373-375,412-418 
INITOR.C, 382-406 
INITOR.DEF, 406 
INITOR.H, 406-408 
INITOR.RC, 408-410 
LED.C, 740-743 
LED.H, 744 
make, 7 

MEMDLL.C, 539-545 
MEMINST.C, 539 
MEMINST.H, 538 
MEMMAP.C, 442-448 
MEMMAP.DLG, 450 
MEMMAP.H, 449 
MEMMAP.RC, 449 
MEMORY.C, 453-465 
MEMORY.DLG, 471-473 
MEMORY.H, 470-473 
MEMORY.RC, 470-473 
MISC.C, 786-788 
MISC.DEF, 790 
MISC.H, 788-789 
MISC.RC, 789-790 
multiple, retrieving, 820 
names 

concatenating, 829 

searching, 818-819 
open dialog, custom, 139-141 
OS2.INI, 374, 509-510 
OS2SYS.INI, 374 


PHONE application, 744 
PHONE.C, 745-772, 780-784 
PHONE.H, 772-774 
PHONE.RC, 774-784 
PIBTIB.C, 792-795 
PIBTIB.DLG, 795-796 
PIBTIB.H, 795 
PRINT.C, 613-620 
PRNT.C, 596-612 
PRNT.DEF, 628 
PRNT.DLG, 592-595 
PRNT.H, 629-631 
PRNT.RC, 631-632 
PRNTINFO.C, 620-628 
searching, 817-830 
selection, 141 

SETTINGS.DLG, 775-776 
SORT.DLG, 665 
STATUS.DLG, 777-778 
SYSINFO.C, 799-801 
system initialization 
entries, 415-418 
INITOR application, 410-412 
SYSTINFO.DLG, 801-802 
SYSTINFO.H, 801 
THERMO.C, 552-560 
THERMO.DEF, 551-552 
THERMO.DLG, 549-562 
THERMO.H, 551 
THERMO.RC, 549 
THREADS.H, 662-663 
THREADS.RC, 663-664 
THUNKASM.ASM, 709-712 
THUNKS.C, 705-708 
THUNKS.DEF, 703 
THUNKS.H, 704-705, 708 
THUNKS.RC, 703 
TID.DLG, 664-665 
FILESRCH.C file, 821-826 
FILESRCH.DLG file, 827-830 
FILESRCH.H file, 827 




fill methods, 272-275 
FillWindow function, 491 
filtering 

messages, 85 
null characters, 721 

FitCheckMarkToSystem function, 211 
flow control, 721 
flowchart, printing, 583 
FNTF_NOVIEWPRINTERFONTS 
specifier, 146 

FNTF_NOVIEWSCREENFONTS 
specifier, 146 

FNTF_PRINTERFONTSELECTED 
specifier, 146 

FNTF_SCREENFONTSELECTED 
specifier, 146 

FNTI_BITMAPFONT font message, 155 
FNTI_DEFAULTLIST font message, 155 
FNTI_FAMILYNAME font message, 155 
FNTI_FIXEDWIDTHFONT font 
message, 155 

FNTI_POINTSIZE font message, 155 
FNTI_PROPORTIONALFONT font 
message, 155 

FNTI_STYLENAME font message, 155 
FNTI_SYNTHESIZED font message, 155 
FNTI_VECTORFONT font message, 

156 

FNTM_FACENAMECHANGED font 
message, 155 

FNTM_FILTERLIST font message, 155 
FNTM_POINTSIZECHANGED font 
message, 156 

FNTM_STYLECHANGED font message, 
156 

FNTM_UPDATEPREVTEW font 
message, 156 

FNTS_APPLYBUTTON specifier, 144 
FNTS_BITMAPONLY flag, 152 
FNTS_BITMAPONLY specifer, 144 
FNTS_CENTER specifier, 144 


FNTS_CUSTOM specifier, 144 
FNTS_FIXEDWIDTHONLY specifier, 

144 

FNTS_HELPBUTTON specifier, 144 
FNTSJNITFROMFATTRS flag, 152 
FNTS_INITFROMFATTRS specifier, 

145 

FNTS_MODELESS specifier, 145 
FNTS_NOSYNTHESIZEDFONTS 
specifier, 145 

FNTS_OWNERDRAWPREVIEW 
specifier, 145 

FNTS_PROPORTIONALONLY 
specifier, 145 

FNTS_RESETBUTTON specifier, 145 
FNTS_VECTORONLY specifier, 145 
FONTDLG structure, 143-149 
clrBack specifier, 147 
clrFore specifier, 147 
f IStyleMask specifier, 147 
f IStyle specifier, 146 
flType specifier, 146 
flTypeMask specifier, 146 
fAttrs specifier, 148 
FNTFJNOVIEWPRINTERFONTS 
specifier, 146 

FNTF_NOVIEWSCREENFONTS 
specifier, 146 

FNTF_PRINTERFONTSELECTED 
specifier, 146 

FNTF_SCREENFONTSELECTED 
specifier, 146 

FNTS_APPLYBUTTON specifier, 144 
FNTS_BITMAPONLY specifer, 144 
FNTS_CENTER specifier, 144 
FNTS_CUSTOM specifier, 144 
FNTS_FIXEDWIDTHONLY 
specifier, 144 

FNTS_HELPBUTTON specifier, 144 
FNTSJNITFROMFATTRS specifier, 
145 


FNTS_MODELESS specifier, 145 
FNTS_NOSYNTHESIZEDFONTS 
specifier, 145 

FNTS_OWNERDRAWPREVIEW 
specifier, 145 

FNTS_PROPORTIONALONLY 
specifier, 145 

FNTSJRESETBUTTON specifier, 

145 

FNTS_VECTORONLY specifier, 145 
HMODULE hMod specifier, 148-150 
lExternalLeading specifier, 148 
IReturn specifier, 147 
1SRC specifier, 147 
ULONG fl specifier, 144 
ULONG flFlags specifier, 145 
ulUser specifier, 147 
FONTMETRICS structure, 316-339 
fonts, 27 

as variables, 151-153 
baseline, 316, 334 
cells, 316 
changing, 150 
classes, 370-372 
code pages, 308, 339-340 
code points, 307 
creating, 329-334 
DBCS, 306 
default, 142, 309 
definition space, 334 
descriptions, 151 

determining memory requirements, 315 
dialog, creating, 142-155 
families, 306-307 
FNTS_BITMAPONLY flag, 152 
FNTS.INITFROMFATTRS flag, 152 
FONTDLG structure, 143-149 
FONTMETRICS structure, 316-339 
glyphs, 307 
image, 142, 152 
image fonts, 307-309 


local identifiers, 151 
logical fonts, 151, 329 
logical inches, 339 
mapping, 329-332 
notification messages 

FNTIJBITMAPFONT, 155 
FNTIJDEFAULTLIST, 155 
FNTI_FAMILYNAME, 155 
FNTI_FIXEDWlDTHFONT, 155 
FNTIJPOINTSIZE, 155 
FNTIJPROPORTIONALFONT, 

155 

FNTLSTYLENAME, 155 
FNTI_S YNTHESIZED, 155 
FNTI_VECT ORFONT, 156 
FNTMJFACENAMECHANGED, 

155 

FNTMJFILTERLIST, 155 
FNTM_POINTSIZECHANGED, 

156 

FNTMJUPDATEPREVIEW, 156 
outline, 142, 307-309 
physical, 151 
point size, 306 
points, 142 
rendering, 307-309 
sans serif, 142 
SBCS, 306 
scaling, 334-336 
serifs, 142, 306 
sFamilyClass field, 370-372 
shearing, 307 
sizing parameters, 147 
style attributes, 308 
System Proportional, 333 
typefaces, 307 

FormatMemListltem function, 470 
formats 

DEF files, 482-485 
export statements, 484 
Frame Control Flags, 40-42 








Frame Contol Identifiers, 42 
frame tracking flags, 74 
frame windows, 15, 49-63 
querying, 123 

subclassing to set mouse pointer, 70-74 
free page state, 423 
FSALLOCATE command, 816 
FSINFO command, 817 
FSQBUFFER2, 803-804 
fsSelection field, 325-326 
function-specific thunks, 699 
functions 

AllocateDlgProc, 472 
Arrangelcons, 120 
ASYNC_GETBAUDRATE, 729 
ASYNC_GETCOMMERROR, 733 
AS YN C_GET COMMEVENT, 
733-734 

ASYNC_GETCOMMSTATUS, 

730- 731 

AS YN C_GETD CBIN F0, 734-736 
AS YN C_GETIN QUECOUNT, 732 
AS YN C_GETLINECTRL, 729-730 
ASYNC.GETLINESTATUS, 731 
AS YN C_GETMODEMINPUT, 732 
ASYNC_GETMODEMOUTPUT, 

731- 736 

ASYNC_GETOUTQUECOUN, 733 
AS YN C„SETB AUDRATE, 723 
ASYNC_SETBREAKOFF, 724-725 
ASYNC_SETBREAKON, 726 
ASYNC_SETDCBINFO, 727-729 
ASYNC_SETLINECTRL, 723-724 
ASYNC_SETMODEMCTRL, 
725-726 

ASYNC_STARTTRANSMIT, 726 
ASYNC_STOPTRANSMIT, 726 
ASYNC_TRANSMITIMM, 724 
BevelWndProc, 532 
CalculatePercentage, 535 
CallCenterWindow, 498 


CallFillWindow, 498 
CascadeChildWindows, 121 
CenterWindow, 469-470, 480, 484, 
532 

ChangeAccessRights, 471 
ChangeCommitState, 471 
conversion, 340 

ConvertToSharedMemory, 441-442 
create_print_DC, 586 
CreateSortingThread, 683 
CreateThreadWindow, 682 
defining, 485 

DestroyThreadWindow, 682 

DevEscape, 582 

device 

dsk_blockremovable, 

804-805 

DSK_GETDEVICEPARAMS, 

804-806 

DevOpenDC, 252, 257, 568, 575-576 
585, 588 

DevPostDeviceModes, 572-574, 585 
DevQueryCaps, 259, 574-579 
DevQueryPiardcopyCaps, 577 
_DO_THUNK, 713 
DOS32FLATTOSEL, 712-713 
DOS32SELTOFLAT, 712-713 
Dos32SelToFlat, 714 
DosAddMuxWaitSem, 658-659 
DosAllocMem, 430-431 
DosClose, 722 
DosCloseEventSem, 649 
DosCloseMutexSem, 652 
DosCloseMuxWaitSem, 656 
DosCreateEventSem, 648-649 
DosCreateMutexSem, 651-652 
DosCreateMuxWaitSem, 655-656 
DosCreateThread, 637-638, 683 
DosDeleteMuxWaitSem, 660 
DosDevIOCtl, 722-736 
DosEnterCritSec, 643, 647 
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DosExitCritSec, 643, 647 
DosExitList, 508-309 
DosFreeModule, 492-493 
DosGetlnfoBlocks, 499, 639-640, 
790-791 

DosKillThread, 638-639 
DosLoadModule, 492-493 
DosOpen, 722 
DosOpenEventSem, 649 
DosOpenMutexSem, 652 
DosOpenMuxWaitSem, 656 
DosPostEventSem, 650 
DosQueryModuleHandle, 499 
DosQueryModuleName, 498-499 
DosQueryMutexSem, 653-654 
DosQueryMuxWaitSem, 659-660 
DosQueryProcAddr, 493, 498 
DosQueryProcAddress, 492 
DosRead, 722 
DosReleaseMutexSem, 653 
DosRequestMutexSem, 652-653 
DosResetEventSem, 649 
DosResumeThread, 642 
DosSetPriority, 640-641 
DosSleep, 642, 686 
DosSuspendThread, 642 
DosWaitEventSem, 650-651 
DosWaitMuxWaitSem, 657-658 
DosWaitThread, 644-645 
DosWrite, 722 
drawing (GPI), 266-267 
enum_key_name, 378 
ExtDeviceMode (Windows 3.x), 
571-572 

external codes, 479 
FillWindow, calling, 491 
FitCheckMarkToSystem, 211 
FormatMemListltem, 470 
get_key_data, 378 
GetAuthorBylndex, 701-702, 713 
GetBooklnformation, 701-702 




GetNextWindowPos, 122 
GpiAssociate, 252-253, 256, 260, 582 
GpiBeginArea, 273-274 
GpiBeginPath, 274 
GpiBox, 262, 266-267, 271, 274-275 
GpiCharExtra, 312 
GpiCharString, 309-310 
GpiCharStringAt, 309-310 
GpiCharStringPos, 309 
GpiCharStringPosAt, 309-311 
GpiCloseFigure, 274 
GpiCreateLogColorTable, 266 
GpiCreateLogFont, 148, 151, 329, 332 
GpiCreatePS, 252-256 
GpiCreateRegion, 275 
GpiDeleteSetld, 332 
GpiDestroyPS, 253, 256 
GpiEndArea, 274 
GpiEndPath, 274-275 
GpiFillPath, 275 

GpiFullArc, 266-267, 271, 274-275 
GpiLine, 267, 271 
GpiModifyPath, 275-277 
GpiMove, 259 
GpiOutlinePath, 275-276 
GpiPartialArc, 267, 270 
GpiPathToRegon, 275 
GpiPointArc, 267 
GpiPolyFillet, 267 
GpiPolyFilletSharp, 267 
GpiPolyLine, 267-268 
GpiPolySpline, 267 
GpiQueryAttrs, 338 
GpiQueryCurrenPosition, 259 
GpiQueryFaceString, 148 
GpiQueryFontMetrics, 137, 152 
GpiQueryFonts, 314-315 
GpiQueryLogColorTable, 266 
GpiQueryPS, 576-578 
GpiQueryTextBox, 337 
GpiReset, 260 




GpiResetPS, 252, 260 
GpiSetAttrs, 260-262, 311, 337-339 
GpiSetBackColor, 260, 311 
GpiSetCharAngle, 334-335 
GpiSetCharBox, 334 
GpiSetCharBreakExtra, 312 
GpiSetCharDirection, 312, 335 
GpiSetCharMode, 336 
GpiSetCharSet, 151, 332 
GpiSetClipPath, 275-277 
GpiSetDefAttrs, 260, 336 
GpiStrokePath, 275-276 
heap management, 425 
importing, 490 
IncrementCount, 502-503 
init_app, 584 

Initialization/Termination, 505-509 
InitializeControlDLL, 517, 532 
InitializeMemDLL, 538 
InitializeMemDll, 547-548 
IOCTL_ASYNC, 723-736 
library, C runtime, 507 
main(), 481 
MainDlgProc, 473 
MemError, 470 

memory management, 426-430 
modifying, 486 

MyWinCreateStdWindow, 485 
Parseltem, 470-472 
path bracket, 283-284 
PlacePopup, 223 
PM, renaming, 485 
PrfCloseProfile, 412 
PrfOpenProfile, 376, 412-413 
PrfQueryProfile, 589 
PrfQueryProfileData, 378, 381 
PrfQueryProfileSize, 377-378 
PrfQueryProfileString, 376, 566 
PrfReset, 376 
PrfWriteProfileData, 382 
PrfWriteProfileString, 382 


PrivateAllocate, 536 
PrivateFree, 536 
PrivateQuery, 536 
process_print, 586 

PS, 254 

QueryDiskSpace, 816 
QueryDrives, 814, 828 
QueryMemory, 451-452, 472 
QueryVolumeLabel, 817 
SearchForFile, 829 
set_path function, 141 
set_title, 136 
SharedAllocate, 536 
SharedFree, 536 
SharedQuery, 536 
SortingDlgProc, 684 
SortingThread, 686 
SplControlDevice, 587 
SplCopyJob, 587 
SplCreateDevice, 588 
SplCreateQueue, 588 
SplDeleteJob, 587 
SplEnumJob, 587 

SplEnumQueue, 413-414, 566-571, 
589-590 

SplHoldJob, 587 
SplHoldQueue, 587 
SplPurgeQueue, 587 
SplQueryDefaultQueue, 571 
SplQueryDevice, 415, 590 
SplQueryJob, 588 

SplQueryQueue, 414-415, 571, 589 
SplReleaseJob, 588 
SplReleaseQueue, 588 
SplSetJob, 588 
spooler, 413-418 
StartSearch, 828 
StopSearch, 829 
strcmp, 477-478 
strcpy, 477- 478 
SwapActionBarMenu, 226 


SwitchToNextChildWindow, 123 
text output, 309-312 
ThermometerThread, 638, 683, 686 
Thermometer WndProc, 534 
ThreadMessageLoop, 685 
threads, 637-645 
TIDDlgProc, 684 
UpdateNumbers, 561 
UPrfWriteProfileString, 379-381 
Win32CreateStdWindow, 485 
Win32StretchPointer, 65 
WinBeginEnumWindows, 35 
WinBeginPaint, 251, 254-256 
WinBroadcastMsg, 80-81 
WinCpTranslateChar, 340 
WinCpTranslateString, 340 
WinCreateMsgQueue, 17, 25 
WinCreateStdWindow, 24, 33, 49, 485 
WinCreateWindow function, 33 
WinDefFontDlgProc, 143 
WinDestroyMsgQueue, 25 
WinDestroyWindow, 33 
WinDispatchMsg, 82-84 
windows, 33-38 
WinDrawBorder, 69 
WinDrawText, 137, 309 
WinEndEnum Windows, 35 
WinEndPaint, 251 
WinFileDlg, 132, 139 
WinFocusChange, 61 
WinFontDlg, 143, 150 
WinGetMinPosition, 34 
WinGetMsg, 17, 82-85 
WinGetmsg, 85 
WinGetNextWindow, 35 
WinGetPS, 251,254 
WinGetScreenPS, 251 
Winlnitialize, 24 
WinlnvalidateRect, 533-534 
WinlsChild, 35, 49 
WinlsWindow, 49 


WinlsWindowShowing, 33 
WinLoadMenu, 219 
WinLoadString, 26 
WinMapWindowPoints, 34 
WinMultWindowFromIDs, 36, 51-52 
WinOpenWindowDC, 252, 257 
WinPeekMsg, 82-85 
WinPostMsg, 80 
WinPostQueueMsg, 80 
WinQueryActiveWindow, 36 
WinQueryCpList, 339 
WinQueryDesktopWindow, 35 
WinQueryFocus, 36, 61 
WinQueryObjectWindow, 35 
WinQueryProfileString, 566 
WinQueryQueueStatus, 85 
WinQuerySysModalWindow, 36 
WinQueryTaskSizePos, 57 
WinQueryWindow, 34, 533 
WinQueryWindowDC, 252, 257 
WinQueryWindowPos, 34, 57 
WinQueryWindowPtr, 37 
WinQueryWindowRect, 34 
WinQueryWindowULong, 37 
WinQueryWindowUShort, 37, 120 
WinReleasePS, 251 
WinSendMsg, 79 
WinSetActiveWindow, 36 
WinSetCp, 339 
WinSetFocus, 36 
WinSetMultWindowPos, 34, 120 
WinSetOwner, 35 
WinSetParent, 14, 34 
WinSetSysModalWindow, 36 
WinSetWindowBits, 38 
WinSetWindowPos, 34, 48, 52 
WinSetWindowULong, 37 
WinSetWindowUShort, 37 
WinShowWindow, 33 
WinShowWindow function, 52 
WinStartApp, 37 





WinSubclassWindow, 63 
WinTerminate, 24, 37 
WinTerminateApp function, 37 
WinWaitMsg, 84-83 
WinWindowFromID, 36 
WinWindowFromPoint, 36 

o 

generic thunks, 699 
get_key_data function, 378 
GetAuthorBylndex function, 701-702, 

713 

GetBooklnformation function, 701-702 
GetNextWindowPos function, 122 
global data versus instance data, 500-505 
global flags with windows, 62 
global initialization, 507 
glyphs (fonts), 307 

GPI (Graphics Programming Interface), 
249-250 

coordinates, 259-260 
drawing functions, 266-267 
functions, 251 
PS handles, 251 

GpiAssociate function, 252-253, 256, 260, 
582 

GpiBeginArea function, 273-274 
GpiBeginPath function, 274 
GpiBitBlt API, 65 

GpiBox function, 262, 266-267, 271, 
274-275 


GpiCreatePS function, 252-256 
GpiCreateRegion function, 275 
GpiDeleteSetld function, 332 
GpiDestroyPS function, 253, 256 
GpiEndArea function, 274 
GpiEndPath function, 274-275 
GpiFillPath function, 275 
GpiFullArc function, 266-267, 271, 
274-275 

GpiLine function, 267, 271 
GpiModifyPath function, 275-277 
GpiMove function, 259 
GpiOutlinePath function, 275-276 
GpiPartialArc function, 267, 270 
GpiPathToRegon function, 275 
GpiPointArc function, 267 
GpiPolyFillet functions, 267 
GpiPolyFilletSharp function, 267 
GpiPolyLine function, 267-268 
GpiPolySpline functions, 267 
GpiQueryAttrs function, 338 
GpiQueryCurrenPosition function, 259 
GpiQueryFaceString function, 148 
GpiQueryFontMetrics function, 137, 152 
GpiQueryFonts function, 314-315 
GpiQuerylogColorTable function, 266 
GpiQueryPS function, 576-578 
GpiQueryTextBox function, 337 
GpiReset function, 260 
GpiResetPS function, 252, 260 
GpiSetAttrs function, 260-262, 311, 


GpiCharExtra function, 312 
GpiCharString function, 309-310 
GpiCharStringAt function, 309-310 
GpiCharStringPos function, 309 
GpiCharStringPosAt function, 309-311 
GpiCloseFigure function, 274 
GpiCreateLogColorTable function, 266 
GpiCreateLogFont function, 148, 151, 
329, 332 


337-339 

GpiSetBackColor function, 260, 311 
GpiSetCharAngle function, 334-335 
GpiSetCharBox function, 334 
GpiSetCharBreakExtra function, 312 
GpiSetCharDirection function, 312, 335 
GpiSetCharMode function, 336 
GpiSetCharSet function, 151, 332 
GpiSetClipPath function, 275-277 
GpiSetDefAttrs function, 260, 336 
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GpiStrokePath function, 275-276 
GRADIENTL structure, 335 
graphics 

areas, 272-274 
drawing primitives, 249 
graphics engine, 250 
paths, 272-277 
retained, 251 


handlers, exit list, 507-509 
handles 
DC, 257 

files, obtaining, 815 
HDIR_CREATE, 819 
HINI, 376 

predefined for windows, 42 
PSs, 251-252 

hardware communication settings, 
720-721 

HDIR_CREATE handle, 819 
header files 

APPSAMP.H, 486-487 
BOOK16.H, 702, 708 
BSEDOS.H, 435 
BSEMEMF.H, 435 
CONTROLS.H, 512-513 
dialog, DIALOG.H, 595-596 
DLLINST.H, 503 
DLLSAMP.H, 482, 494 
DRAW.H, 285-286 
DRIVES.H, 813 
FILESRCH.H, 827 
includes, 43 
INITOR.H, 406-408 
LED.H, 744 
MEMINST.H, 538 
MEMMAP.H, 449 
MEMORY.H, 470-473 
MISC.H, 788-789 


OS2.H, 22-23 
PHONE.H, 772-774 
PIBTIB.H, 795 
PMFONT.H, 364-365 
PRNT.H, 629-631 
SKELETON.H, 26-32 
SYSTINFO.H, 801 
THERMO.PI, 299, 551 
THREADS.H, 662-663 
THUNKS.H, 704-705, 708 
heap management, 430-433 
heap management functions, 425 
hierarchies, parent/child, 634 
HINI file handle, 376 
hMod specifier, 135, 148 
HWNDJDESKTOP identifier, 46 
HWND_OBJECT identifier, 45 


ICON keyword, 28 
ICONEDIT (resource editor), 32 
icons, 27 

changing, 78 
creating, 32, 77 
SKELETON.ICO, 32 
identifiers, predefined, 55-57 
IDM_KILLALLTHREADS command, 
684 

IDM_NEWMSGTHREAD command, 
683 

IDM_NEWSORTINGTHREAD 
command, 683 
idRegistry field, 318 
image bundles, 260, 280 
image fonts, 142, 152, 307-309 
import libraries, 476-480 
creating, 485 
linking, 491 

importing functions, 490 
IMPORTS statement, 490-491 
includes (header files), 43 












IncrementCount function, 502-503 
indexes, defined, 797-798 
information device contexts, 574-577 
information dialog box, phone application, 

737 

INI files, 373-375 
private, 412-418 
spooler functions, 413-418 
init_app function, 584 
initialization 
global, 507 
instance, 507, 511 
initialization files, see INI files 
Initialization/Termination function, 

505-509 

InitializeControlDLL function, 517, 532 
InitializeMemDLL function, 538 
InitializeMemDll function, 547-548 
INITOR application, 376-379 
codes, 382-410 
entries 

adding, 379-381 
deleting, 382 

system initialization files, 410-412 
INITOR.C file, 382-406 
INITOR.DEF file, 406 
INITOR.H file, 406-408 
INITOR.RC file, 408-410 
INSTALL command, 4 
installing 

device drivers (private), 588 
DLLs from OS2.INI, 509-510 
exitlist handlers, 508-509 
sample applications, 4 
instance data 
defining, 502 

versus global data, 500-505 
instance initialization, 507, 511 
INSTANCEDATA variable, constructing, 
503-504 

IOCTL_ASYNC functions, 723-736 


J-K 

job properties, 565, 571-574 
job properties dialog box, 585 
join styles (lines), 277 

key data, INI files, 375 
Key Data window, INITOR application, 
411 

key names, INI files, 375 
KEYB program (keyboard layout), 340 
keyboard layouts 
changing, 340 

German keyboard template (GR), 340 
keywords 
BEGIN, 29 
DESCRIPTION, 31 
END, 29 
EXPENTRY, 481 
EXPORT, 31 
ICON, 28 
LIBRARY, 482 
MULTIPLE, 502 
NAME, 31 
STACK, 485 
SUBMENU, 203 
WINDOWAPI, 31 


lat address space, 420-422 
lAveCharWidth field, 319 
LED controls, 739-743 
LED.C file, 740-743 
LED.H file, 744 
lEmHeight field, 319 
lEmlnc field, 319 
levels, threads, 635-636 
lExternalLeading field, 319 
lExternalLeading specifier, 148 
LIBPATH statement, 492 




libraries 

DLLSAMP.LIB, 485 
import, 476-480 
creating, 485 
linking, 491 
static, 476-480 

library functions, C runtime, 507 
LIBRARY keyword, 482 
line bundles, 261, 264-265 
default attributes, 281-282 
fxWidth field, 264 
IGeomWidth field, 264-265 
ulEnd, 265 
uljoin, 265 
ulType field, 265 
line characteristics 
queries, 729-730 
setting, 723-724 
linear address space, 420-426 
lines 

drawing, 276-277 
join styles, 277 
linking 

dynamic, 492-499 
libraries, import, 491 
static versus dynamic, 476-480 
llnternalLeading field, 319 
lLowerCaseAscent field, 319 
lLowerCaseDescent field, 319 
IMatch field, 327 
IMaxAscender field, 319 
IMaxBaselineExt field, 319 
IMaxCharInc field, 319 
IMaxDescender field, 319 
loading 

DLLs, 478-480, 492-493 
string resources, 26-27 
local identifiers (fonts), 151 
logical addresses, mapping to different 
physical addresses, 501 


logical fonts, 151, 329 
logical inches, 339 
loops 

WinGetMsg, 682 
WinPeekMsg, 682 
IReturn specifier, 134, 147 
ISRC specifier, 134, 147 
IStrikeoutPosition field, 327 
IStrikeoutSize field, 326 
lSubscriptXOffset field, 326 
lSubscriptXSize field, 326 
lSubscriptYOffset field, 326 
lSubscriptYSize field, 326 
lSuperscriptXOffset field, 326 
lSuperscriptXSize field, 326 
lSuperscriptYOffset field, 326 
lSuperscriptYSize field, 326 
lUnderscorePosition field, 326 
lUnderscoreSize field, 326 
lXHeight field, 319 

M 

macros 

BSEMEMF.H header file, 435 
data conversion, 693-694 
WinSetCheckMark, 211-212 
main thread, 634 
main windows, 12 
main() function, 481 
MainDlgProc function, 473 
make files, 7 

MAKEINI program, 412 
management, heap, 430-433 
mapping fonts, 329-332 
mapping modes, PU_LOMETRIC, 584 
marker bundles, 261 

default attributes, 282-283 
sizefxCell, 266 
usSet field, 265 
usSymbol, 266 
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MENUITEM structure, 182 
messages, 185-186, 230-247 
mnemonics in, 184 
MS_ACTIONBAR style, 224 
notification messages, 247-248 
pop-up, 179, 218-225 
pull-down, 178 
selecting items, 186-187 
styles, 181-226 
submenus, 178, 227-228 
top-level, 178 
types, 178-179 

WC_MENU window class, 178 
MENUXTRA.H file, 199-200, 211-212 
message boxes, system error display, 806 
message queues, 16-18 
creating, 25 
destroying, 25 
posting to, 80 
redundant messages, 25 
size, 17 

threads, 645, 739 

additional, creating, 686 
creating, 829 
destroying, 829 
dialog windows, 661 
multiple, 687-688 
suspending, 646 
messages 

applications, 15-18 
BVM_SETCOLOR, 533 
BYPOS suffix, 186 
communication methods 
posting, 79 
sending, 78 
custom, 87 
dispatching, 83 
error 

ERRORJBUFFERJ3VERELOW, 

803 


ERROR_DRIVE_N OT_READY, 
803 

ERROR_INVALID_DRIVE, 803 
filtering, 85 

in menus, 185-186, 230-247 
MM_DELETEITEM menu message, 
233 

MMJDELETEITEMBYPOS menu 
message, 233 

MM_ENDMENUMODE menu 
message, 236-237 

MM_INSERTITEM menu message, 
232 

MMJTEMIDFROMPOSITION 
menu message, 243 
MMJTEMPOSITIONFROMID 
menu message, 242-243 
MM_MATCHMNEMONIC menu 
message, 246-247 
MM_PORTHOLEINIT, 227-228 
MM.QUERYITEM menu message, 
233-234 

MM_QUERYITEMATTR menu 
message, 243-244 
MM_QUERYITEMATTRBYPOS 
menu message, 244 
MM_QUERYITEMBYPOS, 227-228 
MM_QUERYITEMBYPOS menu 
mesage, 234 

MM_QUERYITEMCOUNT menu 
message, 235 

MM_QUERYITEMTEXT menu 
message, 239-240 

MM_QUERYlTEMTEXTBYPOS 
menu message, 240 
MM_QUERYITEMTEXTLEN GTH 
menu message, 240-241 
MM_QIMIYTTEMTEXTI£NGTM 
menu message, 241 
MM_QUERYSELITEMID menu 
message, 239 




MM_REMOVEITEM menu message, 
237 

MM_REMOVEITEMBYPOS menu 
message, 237 

MM_SELECTITEM menu message, 
237-238 

MM_SELECTITEMBYPOS menu 
message, 238-239 
MM_SETITEM menu message, 
234-233 

MM_SETITEMATTR menu message, 
244 

MM_SETITEMATTRBYPOS menu 
message, 245 

MM_SETITEMBYPOS menu 
message, 235 

MM_SETITEMCHECKMARK menu 
message, 245 

MM_SETITEMCHECKMARKBYPOS 
menu message, 246 
MM.SETITEMHANDLE menu 
message, 241 

MM_SETITEMHANDLEBYPOS 
menu message, 241-242 
MM_SETITEMTEXT menu message, 
242 

MM_SETITEMTEXTBYPOS menu 
message, 242 

MM_STARTMENUMODE menu 
message, 235 
mouse, 534 

notification messages in menus, 186 
order, 18 

PMWIN.H file, 16 

posting, 25, 80 

posting to queues, 80 

priority, 86 

processing, 78-87 

receiving, window procedures, 18 

redundant messages in queue, 25 

retrieving, 17, 82 


structure, 16 
system-initiated, 16 
THM_SETCOLOR, 561 
user-initiated, 16 
WinGetMsg function, 17 
WM_COMMAND, 684 
WM_CONTROL, 14 
WM_CREATE, 532 
WM_ERASEBACKGROUND, 253 
WM_FOCUSCHANGE, 62-63 
WMJHITTEST, 533, 687-688 
WMJNITDLG, 560, 586, 708-709 
WM_MENUSELECT, 14, 186-187 
WM_MINMAXFRAME, 60 
WM_PAINT, 253, 533 
WM_PRINT„STATUS, 586 
WM_QUIT, 685 
WM_START_PRINT, 586, 688 
WM_USER_CRITSECTION, 685 
WM_USER_DOWNPR!ORITY, 685 
WM_USER_KILL, 685 
WM_USER_PERCENTCOMPLETE, 
671, 684-686 

WM_USER_SEMAPHORE, 685 
WM_USER_UPPRIORITY, 685 
micro PSs 

GpiAssociate function, 256 
GpiCreatePS function, 254-256 
GpiDestroyPS function, 256 
handles, 252 

WinBeginPaint function, 256 
minimized windows, visibility, 52 
minimizing windows, 14, 53 
MISC application, 785-830 
MISC.C file, 786-788 
MISC.DEF file, 790 
MISC.H file, 788-789 
MISC.RC file, 789-790 
MM_DELETEITEM message, 233 
MM_DELETEITEMBYPOS message, 

233 
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MM_ENDMENUMODE message, 
236-237 

MM_INSERTITEM message, 232 

MMJTEMIDFROMPOSITION 
message, 243 

MMJTEMPOSITIONFROMID 
message, 242-243 

MM_MATCHMNEMONIC message, 
246-247 

MM_PORTHOLEINIT message, 
227-228, 248 

MM_QUERYITEM message, 233-234 

MM_QUERYITEMATTR message, 
243-244 

MM_QUERYITEMATTRBYPOS 
message, 244 

MM_QUERYITEMBYPOS message, 

234, 227-228 

MM_QUERYTTEMCOUNT message, 
235 

MM_QUERYITEMTEXT message, 
239-240 

MM_QUERYITEMTEXTBYPOS 
message, 240 

MM_QUERYITEMTEXTLENGTH 
message, 240-241 

MM_QUERYITEMTEXTLENGTHBYPOS 

message, 241 


MM_SETITEMCHECKMARK message, 
245 

MM_SETITEMCHECKMARKBYPOS 
message, 246 

MM_SETITEMHANDLE message, 241 
MM_SETITEMHANDLEBYPOS 
message, 241-242 

MM_SETITEMTEXT message, 242 
MM_SETITEMTEXTBYPOS message, 
242 

MM_STARTMENUMODE message, 

235 

mnemonics (menus), 184 
modal dialogs, 132 
modeless dialogs, 153, 828 
modem control signals, 725-726 
modes, mapping, 584 
modifying, window Z-order, 48 
module definition files 
SKELETON.DEF, 31-32 

syntax, 31 
mouse 

messages, 534 
pointer, 69-77 

in client window, 69 
modifying with 

Win32StretchPointer function, 65 
subclassing the frame window, 70-74 
values, 55 


li 4gi;||| 

MM_REMOVEITEM message, 237 

moving windows, 59-60 


MM_REMOVEITEMBYPOS message, 

MS_ACTIONBAR style (menus), 224 

| ‘1117■ 11. : ■. 

237 

Multiple Document Interface applications, 

ifiiiii 

MM_$ELECTITEM message, 237-238 

see MDI applications 

ililii 

MM_SELECTITEMBYPOS message, 

multiple exitlist handlers, 509 


238-239 

threads, 687-688 

. 

m 

MM_SETITEM message, 234-235 

multiple files, retrieving, 820 

;v-7 iIr Hill 

MM_SETITEMATTR message, 244 

MULTIPLE keyword, 502 

I1SI1IMI8I 

MM_SETITEMATTRBYPOS message, 

multiple wait semaphores, 647, 654-660 


245 

multitasking operating systems, 420, 

0mimvi 

MM_SETITEMBYPOS message, 235 

633-635 
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MUST_HAVE_DIRECTORY file 
attribute, 830 

mutex semaphores, 631-654 
mutual exclusion semaphores, 647, 
651-654 

muxwait semaphores, 654-660 
MyWinCreateStdWindow function, 485 


NAME keyword, 31 
named semaphores, 647 
named shared memory, 434-436 
nesting, critical sections, 644 
no-wait read timeout, 720 
nondefault values in file dialog, 136-138 
nonmessage queue threads, 645, 662 
nonshared memory, 426-430 
normal PSs 

GpiAssociate function, 256 
GpiCreatePS function, 254-256 
GpiDestroyPS function, 256 
handles, 252 

WinBeginPaint function, 256 
notification messages 
font type, 155-156 
menus type, 186, 247-248 
MM_PORTHOLEINIT, 248 
WM_MENUCHAR, 247-248 
null stripping, 721 


object windows, 46 
objects 

print, 563-566, 571 
resources, 278 
offset printer, 578-579 
OPEN_FLAGS_DASD flag, 815 
operating systems, multitasking, 420, 
633-635 

ordinal numbers in DLLs, 484, 491 


OS/2 

default fonts, 142 
installed print devices, 566 
KEYB program, 340 
memory architecture, 419 
printing, 565-566 
OS2.H header file, 22-23 
OS2.INI file, 374, 509-510 
OS2SYS.INI, 374 
outline fonts, 142, 307-309 
ownership (windows), 14-15 


packing, segment, 695-696 
pages 

committed, 428 
determining size, 578-579 
memory systems, 420, 423-426 
page tables, 501-502 
painting titlebar, 65-69 
panose structure, 328 
papszFQFilename specifier, 136 
papszIDriveList specifier, 135 
papszITypeList specifier, 135 
parameters 

DosDevlOCtl function, 722-723 
pushing, 713 
parent processes, 634 
parent windows, 12-14 
parity 

checking, 720 
errors, 721 

Parseltem function, 470-472 
partitions, address space, 420 
passing addresses 

16-bit to 32-bit, 694 
across 64K boundaries, 694-695 
from 32- to 16-bit code, 693-695 
paths (graphics), 272-277 
closing, 275 






fill methods, 272-275 
peer status, threads, 635 
pfnDlgProc specifier, 135 
phone application, 736-784 
files, 744 
PHONE.C file 
code, 745-772 
process, 780-784 
PHONE.H file, 772-774 
PHONE.RC file, 774-784 
threads, 739 
physical fonts, 151 

PIB (Process Information Block), 790-792 
PIBTIB.C file, 792-795 
PIBTIB.DLG file, 795-796 
PIBTIB.H file, 795 
pipes, 646 

PlacePopup function, 223 
PM (Presentation Manager), 12 
DLLs, 475 

minimum stack size, 31 
renaming functions, 485 
PMDRAW application 
DRAW.C file, 286-297 
DRAW.H file, 285-286 
DRAW.RC file, 298-299 
necessary files, 285 
THERMO.C file, 299-304 
THERMO.H file, 299 
PMFONT application 
client window, 316 
FamilyNameAtom field, 327 
fsSelection field, 325-326 
idRegistry field, 318 
lAveCharWidth field, 319 
lEmHeight field, 319 
lEmlnc field, 319 
lExternalLeading field, 319 
llnternalLeading field, 319 
list box, 316 

lLowerCaseAscent field, 319 


lLowerCaseDescent field, 319 
IMatch field, 327 
IMaxAscender field, 319 
IMaxBaselineExt field, 319 
IMaxCharInc field, 319 
IMaxDescender field, 319 
IStrikeoutPosition field, 327 
IStrikeoutSize field, 326 
lSubscriptXOffset field, 326 
lSubscriptXSize field, 326 
lSubscriptYOffset field, 326 
lSubscriptYSize field, 326 
lSuperscriptXOffset field, 326 
lSuperscriptXSize field, 326 
lSuperscriptYOffset field, 326 
lSuperscriptYSize field, 326 
lUnderscorePosition field, 326 
lUnderscoreSize field, 326 
lXHeight field, 319 
panose structure, 328 

PMFONT.C, 340-363 
PMFONT.DEF, 370 
PMFONT.DLG, 367-369 
PMFONT.H file, 364-365 
PMFONT.RC file, 365-367 
required files, 340 
rotation, 337 
sBreakChar field, 323 
sCharRot field, 321 
sCharSlope field, 320 
sDefaultChar field, 323 
sFamilyClass field, 327 
sFirstChar field, 323 
shearing, 337 
slnlineDir field, 320 
sKerningPairs field, 327 
sLastChar field, 323 
sMinimumPointSize field, 324 
sNominalPointSize field, 324 
sXDeviceRes field, 322 
sYDeviceRes field, 323 











szFacename array, 318 
szFamilyname array, 318 
usCapabilities field, 326 
usCodePage field, 318 
usDefn field, 325 
usType field, 324-325 
usWeightClass field, 321-322 
usWidthClass field, 322 
PMFONT.C, 340-352 
PMFONT.DEF, 370 
PMFONT.DLG, 367-369 
PMFONT.H, 364-365 
PMFONT.RC, 365-367 
PMGPI command, 508 
PMPLOT queue processor, 566 
PMPRINT queue driver, 565 
PM WIN command, 508 
point size, 306 
pointer, see mouse: pointer 
pointers 

SPTR_ARROW, 469 
SPTR_WAIT, 469 

values, 55 

POINTL structure, 335 
points, 142 

pop-up menus, 179, 218-225 
port settings, 738-739 
positioning windows, 34 
posted messages, 79 
posted state, event semaphores, 648 
posting messages, 25, 80 
pragma statements, 697-698 
presentation driver, 250 
Presentation Manager, see PM 
presentation spaces, see PSs 
PrfCloseProfile function, 412 
PrfOpenProfile function, 376, 412-413 
PrfQueryProfile function, 589 
PrfQueryProfileData function, 378, 381 
PrfQueryProfileSize function, 377-378 
PrfQueryProfileString function, 376, 566 


PrfReset function, 376 
PrfWriteProfileData function, 382 
PrfWriteProfileString function, 382 
primitives, 272 
PRINT.C file, 613-620 
printing 

applications, 582-586 
confirmation dialog box, 586 
device context, 568, 579-582 
device independence, 564-565 
DOS applications, 564-565 
drivers, 564-565 
flowchart, 583 
jobs 

spooling, 566 
tracking, 586-588 
objects, 563-566, 571 
OS/2 1.x, 565 
printer offset, 578-579 
printer properties versus job properties, 
571-574 

process, 579-582 
selection dialog box, 584 
status dialog box, 586 
Windows 3.x, 565 
priorities 

ABSOLUTE, 636 
DYNAMIC, 636 
messages, 86 

threads, 635-636, 640-642 
privacy 

INI files, 412-418 
device drivers, 588 
memory, 420-421 
memory objects, 545-546 
page state, 423 
semaphores, 647 
window classes, 38 
PrivateAllocate function, 536 
PrivateFree function, 536 
PrivateQuery function, 536 






PRNT application, 592-612 
PRNT.C files, 596-612 
PRNT.DEF file, 628 
PRNT.DLG file, 592-595 
PRNT.EXE requirements, 582-586 
PRNT.H file, 629-631 
PRNT.RC file, 631-632 
PRNTINFO.C file, 620-628 
process address space, 420 
Process Information Block, see PIB 
process_print function, 586 
processes 

DATA MULTIPLE NONSHARED, 
502-504 

DATA SINGLE SEIARED, 501-505 
multitasking, 634 
queue, 565-566 
processing messages, 18, 78-87 
profile management API, 374-382 
profile queries, converting, 588-591 
programming 

32-bit versus 16-bit, 691-692 
common dialogs, 125-130 
programs 

APPSAMP2, 494-499 
MAKEINI, 412 
THREADS.C, 665-682 
see also applications 
properties, 565, 571-574 
PRQINF03 structure, 568-570 
PRQINF06 structure, 568-570 
PSs (presentation spaces) 
bundles, 260-262 
creating, 251-253 

default attributes table, 260, 278-283 


QueryMemory function, 451-452, 472 
QueryVolumeLabel function, 817 
Queue And Printer Details dialog, 577 
queue processors, 565-566 
queued device contexts, 579 
queues, 646 

receive, 718-720 
transmit, 718-720 
see also message queues 


read timeout, 720 
Receive Flow Control, 721 
ReceiveData Thread, 750, 783-784 
receiving 

data threads, 736, 739 
queue, 718-720 








records relocation, 478-479 
RECTL structures, 58 
registering window classes, 26 
relocation records, 478-479 
removing exitlist handlers, 508-509 
renaming functions, 485 
rendering fonts, 307-309 
RES file extension, 27 
reset state, event semaphores, 648 
resizing 

bitmaps, 211 

memory objects after allocation, 425 
resolution-specific DLLs, 510 
resource compilers, 29 
resource editors, 32 
resource files 

APPSAMP.RC, 487 

defining application elements, 27-28 

DRAW.RC, 298-299 
INITOR.RC, 408-410 
MEMMAP.RC, 449 
MEMORY.RC, 470-473 
MISC.RC, 789-790 
PHONE.RC, 774-784 
PMFONT.RC, 365-367 
PRNT.RC, 631-632 
SKELETON.RC, 27-30 
THERMO.RC, 549 
THREADS.RC, 663-664 
THUNKS.RC, 703 
resource-only DLLs, 510 
resources, 278 
restoring windows, 53-54 
restricting windows, 75-77 
resuming threads, 642 
retained graphics, 251 
retrieving 

DCs, 257-259 
messages, 17, 82 
multiple files, 820 


PSs, 251-253 
windows, 57-58 

return values for window procedures, 19 

RGB mode (colors), 266 

RGB value (colors), 266 

rgf parameter, 80 

ROP (raster operation) codes, 65 

runtime dynamic linking, 492-499 


sans serif fonts, 142, 306 
Save As dialog, 141 
saving 

module handles, DLLs, 531 
screen location, 412 
SBCS (single-byte character set), 306 
sBreakChar field, 323 
scaling fonts, 334-336 
sCharRot field, 321 
sCharSlope field, 320 
screen coordinates, converting windows 
to/from, 59 

screen location, saving, 411 
sDefaultChar field, 323 
SearchForFile function, 829 
searching files, 817-830 
sections, critical, 643-644 
segment packing, 695-696 
SEGMENTS statement, 504 
selecting 

compliers, 5 
menu items, 186-187 
selectors, 16-bit, 692-693 
semaphores, 646-660, 783 
SEMRECORD structure, 655 
sent messages, 78 
serifs, 142, 306 

SET COMPILER command, 5 
set_path function, 141 
set_titie function, 136 
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setting 

checkmarks (menu items), 207 
mouse pointer, 69 
windows 

position, 59 
size, 59 

settings, communications, 720-721 
settings dialog box, phone application, 738 
SETTINGS.DLG file, 775-776 
sFamilyClass field, 327 
sFamilyClass field (fonts), 370-372 
sFirstChar field, 323 
sharing 

memory, 420-421, 434-442 
memory objects, tracking, 546 
page state, 423 
semaphores, 647 
SharedAllocate function, 536 
SharedFree function, 536 
SharedQuery function, 536 
shearing (fonts), 307 
SHORT sEAType specifier, 136 
SHORT x specifier, 136 
SHORT y specifier, 136 
sibling windows, 12 
signaling 

active windows, 62-63 
inactive windows, 62-63 
signals, modem control, 725-726 
single-byte character set, wSBCS 
slnlineDir field, 320 
sizing 

memory objects after allocation, 425 
windows, 34, 59-60 
SKEFETON application, 6-9, 19-23 
application window, 24 
Main Procedure, 23-26 
message queues, 25 
SKEFETON.C, 20-24 
SKEFETON.DEF, 31-32 
SKELETON.H, 26-32 


SKELETON.ICO, 32 
SKELETON.RC 
compiling, 29-30 
creating, 27-29 
sKerningPairs field, 327 
sLastChar field, 323 
sMinimumPointSize field, 324 
sNominalPointSize field, 324 
software, see applications; programs 
SORT.DLG file, 665 
SORTDATA structure, 683 
sorting threads, 662, 668 
SortingDlgProc function, 684 
SortingThread function, 686 
spacing (characters), 312-313 
sparse memory pages, 424 
spinner control, initializing, 560-561 
SplControlDevice function, 587 
SplCopyJob function, 587 
SplCreateDevice function, 588 
SplCreateQueue function, 588 
SplDeleteJob function, 587 
SplEnumJob function, 587 
SplEnumQueue function, 413-414, 
566-571, 589-590 
SplHoldJob function, 587 
SplHoldQueue function, 587 
SplPurgeQueue function, 587 
SplQueryDefaultQueue function, 571 
SplQueryDevice function, 415, 590 
SplQueryJob function, 588 
SplQueryQueue function, 414-415, 571, 
589 

SplReleaseJob function, 588 
SplReleaseQueue function, 588 
SplSetJob function, 588 
spooler API 

replacement, 589-591 
tracking print jobs, 586-588 
spooler functions, 413-418 
spoolers, 566 




SPTR_ARROW pointer, 469 
SPTR_WAIT pointer, 469 
STACK keyword, 485 
StartSearch function, 828 
statements 

DATA, 482-483 
export, 484 
IMPORTS, 490-491 
LIBPATH, 492 
MEMMAN, 695 
pragma, 697-698 
SEGMENTS, 504 
THREADS, 636 
static libraries, 476-480 
static linking, 476-480 
STATUS.DLG file, 777-778 
stop bits, 720 
StopSearch function, 829 
strcmp function, 477-478 
strcpy function, 477-478 
strings 

converting to/from code pages, 340 
loading resources, 26-27 
tables, 27-29 
structures 

alignment of elements, 697-698 
DEVICEINFO, 584 
FILEFINDBUF3, 819 
PRQINF03, 568-570 
PRQINF06, 568-570 
SEMRECORD, 655 
SORTDATA, 683 
styles 

attributes, 308 
bevels, 513-514 
window classes, 39 

suballocated memory, 430-433, 439-441 
subclassing 
titlebar, 65 
windows, 63-64 
SUBMENU keyword, 203 


submenus, 178 

copying to multiple menus, 227-228 
creating, 184, 203-205 
MM_PORTHOLEINIT message, 
227-228 

MM_QUERYITEMBYPOS message, 
227-228 

suspending threads, 642, 646 
SwapActionBarMenu function, 226 
SwitchToNextChildWindow function, 
123 

sXDeviceRes field, 322 
sYDeviceRes field, 323 
syntax, module definition files, 31 
SYSINFO.C file, 799-801 
system error message box, display, 806 
system information files, SYSINFO.C, 
799-801 

system initialization files 
entries, 415-418 
INITOR application, 410-412 
system menu 

attaching options, 228-229 
supplemental menu, 229 
System Proportional font, 333 
system settings, threads, 636-637 
system-initiated messages, 16 
SYSTINFO.DLG file, 801-802 
SYSTINFO.H file, 801 
szFacename array, 318 
szFamilyname array, 318 
szFullFile specifier, 136 

T 

tables, page, 501-502 
templates, custom, 138-141 
terminating threads, 638-639 
text 

character reference point, 309, 312 
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characters 

altering spacing, 312 
ascent, 316 
descent, 316 
drawing primitives, 249 
output, 312-313 

changing direction, 335 
functions, 309-312 
presentation space attributes, 
312-313 

THERMO.C, 299-304 
THERMO.H, 299 

THERMOMETER application, 510-562 
THERMO.C file, 552-560 
THERMO.DEF file, 551-552 
THERMO.DLG file, 549-562 
THERMO.H file, 551 
THERMO.RC file, 549 
THERMOMETER control, 510, 560 
thermometer threads, 673 
thermometer window, 516, 531, 534-535 
Thermometer WndProc function, 534 
THERMOMETERCLASS class, 515-516 
ThermometerThread function, 638, 683, 
686 

THM_SETCOLOR message, 561 
thread demonstration application, 660-689 
Thread Information Block, see TIB 
ThreadMessageLoop function, 685 
threads, 15, 24 
CommStatus, 748 
CommStatusThread, 783 
communications status, 739, 781 
creating, 637-638 
data sharing problems, 643 
designing, 645-646 
dispatch priority, 635-636 
functions, 637-645 
information, obtaining, 790-796 
main, 634 

message queue, 645, 739 


additional, creating, 686 
creating, 829 
destroying, 829 
dialog windows, 661 
multiple, 687-688 
suspending, 646 
multitasking, 634-635 
nonmessage queue, 645, 662 
phone application, 739 
priorities, setting, 640-642 
receive data, 736, 739 
ReceiveData, 750, 783 
ReceiveDataThread, 784 
resuming, 642 
sorting, 671 
suspending, 642 
system settings, 636-637 
terminating, 638-639 
thermometer, 673 
THREADS statement, 636 
THREADS.C program, 665-682 
THREADS.H file, 662-663 
THREADS.RC file, 663-664 
Thunk application, 700-715 
THUNKASM.ASM file, 709-712 
thunks, 422, 698-699 

calling, WM_INITDLG message, 
708-709 

creating, 714-715 
THUNKS application 

THUNKS.C file, 705-708 
THUNKS.DEF file, 703 
THUNKS.H file, 708, 704-705 
THUNKS.RC file, 703 
TIB (Thread Information Block) structure, 
790-791 

TID.DLG file, 664-665 
TIDDlgProc function, 684 
tiled memory, 422, 692-695 
time slices, 635-636, 640 
timeout, read, 720 


TIMESLICE command, 637 
titlebar 

painting, 63-69 
subclassing, 65 
top-level windows, 46 
top-level menus, 178 
tracking 

print jobs, 586-588 
private memory objects, 545-546 
shared memory objects, 546 
windows, 74-75 
transmission 
errors, 721 
turning off, 726 
turning on, 726 
Transmit Flow Control, 721 
transmit queues, 718-720 
TTY sessions, starting, 738-739 
typefaces, 307 

U 

ulFQFCount specifier, 136 
ULONG ulUser specifier, 134 
ULONG fl specifier, 144 
ULONG flFlags specifier, 145 
ULONG values, 55 
ulUser specifier, 147 
uncommitted memory, allocating, 469 
uncommitted pages, memory, 423-426 
unnamed shared memory, 434 
allocating, 435 
memory access, 436-439 
unshared memory, converting to shared, 

441-442 

UpdateNumbers function, 561 
updating actionbar, 225-226 
UPrfWriteProfileString function, 379-381 
usCapabilities field, 326 
usCodePage field, 318 
usDefn field, 325 


usDlgld specifier, 136 
user-initiated messages, 16 
USHORT values, 55 
usType field, 324-325 
usWeightClass field, 321-322 
usWidthClass field, 322 

V 

values 

pointer, 55 
system, 797-798 
ULONG, 55 
USHORT, 55 

variables 

fonts as, 151-153 
INSTANCEDATA, 503-504 
viewing areas, phone application, 736-737 
virtual consoles, 634 
virtual memory addresses, 692 
volume labels, drives, 815-816 


wait-for-something timeout, 720 
WCJBUTTON window class, 38 
WC_CONTAINER window class, 38 
WC_ENTRYFIELD window class, 38 
WC_FRAME window class, 38 
WC_LISTBOX window class, 38 
WC_MENU window class, 38, 178 
WC_NOTEBOOK window class, 38 
WC_SCROLLBAR window class, 38 
WC_SLIDER window class, 38 
WC_SPINBUTTON window class, 38 
WC_STATIC window class, 38 
WC_TITLEBAR window class, 38 
WC_VALUESET window class, 38 
Win32CreateStdWindow function, 485 
Win32StretchPointer function, 65 
WinBeginEnumWindows function, 35 
WinBeginPaint function, 251, 254-256 
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WinBroadcastMsg function, 80-81 
WinCpTranslateChar function, 340 
WinCpTranslateString function, 340 
WinCreateMsgQueue function, 17, 25 
WinCreateStdWindow function, 24, 33, 
49, 485 

WinCreateWindow API, 50 
WinCreateWindow function, 33 
WinDefFontDlgProc function, 143 
WinDestroyMsgQueue function, 25 
WinDestroyWindow function, 33 
WinDispatchMsg function, 82-84 
window classes 

defining subclass window functions, 
118 

preregistered, 15 
private, 38 
public, 38 
registering, 26 
standard, 38 
styles, 39 

WC_MENU, 178 
window enumeration loop, 48 
WINDOWAPI keyword, 31 
windows, 11-15 
activating, 61-63 
active, 61-63 
APPSAMP, 490 
bevel, 510, 532-534 
calculating positions, 58 
calculating size, 59 
changing 
focus, 61 
owner, 15, 48-49 
parents, 14, 48-49 
visibility, 33 
characteristics, 52-54 
child windows, 12-14 
classes, 18 
client area, 15 





converting to/from screen coordinates, 
59 

creating, 20-24, 33 
data structure, 54-57 
deactivating, 61 
default position, 57 
default size, 57 
desktop, 12 
destroying, 20-24, 33 
disabled, 53, 61 

disabling with WinEnableWindow API 
53 

drawing, 46 
enabled, 52-53 
enumerating, 48 
focus, 61 

frame window, 15, 49-63 
functions, 33-38 
handles 

predefined, 42 
querying, 51 
hierarchy, 12-13 
icons, 77-78 
inactive, 62-63 

Key Data, INITOR application, 411 

main, 12 

maximizing, 53 

minimizing, 52-53 

moving, 59-60 

object, 46 

ownership, 14-15 

negating movement, 60 
threads, 15 
parameters, 61 
parent, 12-14 

parent-child relationship, 12-14, 46-49 
phone application, 736-738 
positioning, 34, 57-60 
preregistered classes, 15 








procedures 

receiving messages, 18 
return values, 19 
querying, 46-47 
restoring, 53-54 
restricting 

movement, 74-76 
size, 75-77 
retrieving, 57-58 
sibling, 12 
size, 34, 57-60 
styles, 39-40 
subclassing, 63-64 
templates, 28 
top-level, 46 
tracking, 74-75 
window enumeration loop, 48 
WS.VISIBLE flag, 52 
Z-order, 46-48 
Windows 3.x 

ExtDeviceMode function, 571-572 
printing, 565 

WinDrawBorder API, 533 
WinDrawBorder function, 69 
WinDrawText function, 137, 309 
WindSetWindowUShort API, 55 
WinEnableWindow API, 53 
WinEndEnumWindows function, 35 
WinEndPaint function, 251 
WinFileDlg function, 132, 139 
WinFocusChange function, 61 
WinFontDlg function, 143, 150 
WinGetMinPosition function, 34 
WinGetMsg function, 17, 82-85 
WinGetmsg function, 85 
WinGetMsg loops, 682 
WinGetNextWindow function, 35 
WinGetPS function, 251, 254 
WinGetScreenPS function, 251 
Winlnitialize function, 24 
WinlnvalidateRect function, 533-534 


WinlsChild function, 35, 49 
WinlsWindow function, 49 
WinlsWindowSbowing function, 33 
WinLoadMenu function, 219 
WinLoadString function, 26 
WinMapWindowPoints API, 58 
WinMapWindowPoints function, 34 
WinMultWindowFromIDs function, 36, 
51-52 

WinOpenWindowDC function, 252, 257 
WinPeekMsg function, 82-83, 85 
WinPeekMsg loops, 682 
WinPopupMenu API, 218-220 
WinPostMsg function, 80 
WinPostQueueMsg function, 80 
WinQueryActiveWindow function, 36 
WinQueryCpList function, 339 
WinQueryDesktopWindow function, 35 
WinQueryFocus function, 36, 61 
WinQueryObjectWindow function, 35 
WinQueryProfileString function, 566 
WinQueryQueueStatus function, 85-86 
WinQuerySysModalWindow function, 36 
WinQueryTaskSizePos function, 57 
WinQueryWindow function, 34, 533 
WinQueryWindowDC function, 252, 257 
WinQueryWindowPos API, 57 
WinQueryWindowPos function, 34, 57 
WinQueryWindowPtr function, 37 
WinQueryWindowPtr API, 55 
WinQueryWindowRect API, 58 
WinQueryWindowRect function, 34 
WinQueryWindowULong function, 37 
WinQueryWindowULong API, 55 
WinQueryWindowUShort function, 37, 
120 

WinQueryWindowUShort API, 55 
WinReleasePS function, 251 
WinSendMsg function, 79 
WinSetActiveWindow function, 36 
WinSetCheckMark macro, 211-212 




W M_EKAoEdACK.GK(J U N ]J message, 
253 

WMJFOCUSCHANGE message, 62-63 
WM_HITTEST message, 533, 687-688 
WM_INITDLG message, 560, 586, 
708-709 

WMJMENUCHAR messages, 247-248 
WM_MENUSELECT message, 14, 
186-187 

WM_MINMAXFRAME message, 60 
WM_PAINT message, 253, 533 
WM_PRINT_STATUS message, 586 
WM_QUIT message, 685 
WM_START_PRINT message, 586-688 
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